kubernetes / kubernetes/website

Add distinction for "deprecated" vs "removed" API versions in the style guide

Open
#28,690 17 comments 1 reaction 0 assignees View on GitHub
kind/feature lifecycle/frozen priority/backlog sig/docs triage/accepted
Dominant language
HTML
Stars
5.4k
Forks
15.7k
Avg merge
4d 18h
Merged PRs (30d)
204

Description

Based on discussion in sig-docs meeting on June 29 2021.

We're talking about improving our comms and exposure for deprecated API versions each release to make upgrading a little less *fun*.

We should add a section to the contributor style guide where we talk about the different terms we use when talking about APIs, such as "removing", "deprecating", "obsolete", "no longer serving". We should have:

* Preferred terms and when you should use them
* Common use cases and examples of deprecation and removal warnings
* A list of words we should avoid using when talking about API changes

/cc @chrisnegus @jimangel @sftim
/sig docs

Contributor guide

Open the contributing guide

Research direction

Locate the contributor style guide in the Kubernetes website repository and review the discussion referenced in this issue, including the SIG Docs context. Done means the guide clearly defines preferred terms for deprecation and removal, gives relevant warning examples, and lists terms to avoid.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.