* Loosen the meaning of status in API conventions
As per KEP https://github.com/kubernetes/enhancements/issues/2527 -
remove the "from observation" guidance and add some discussion of when
to use status fields vs. additional types for allocated resources.
* Backtick spec and status
* Act on feedback
API conventions had two semi-duplicated sections for
object references, with slightly different guidance.
Consolidating guidance to point to the most recent
guidance.
Clarifying the naming recommendations for naming of lists
of object references, as the guidance was not explicit.
- switching fieldpath syntax to reference best practices already in the
spec
- clarifying naming of the object reference field
- fixing a poor example with a kind used where a resource value should
have been.
- switched from kind to resource.
- extended examples to four kinds of object references.
- clarified use of JSON Pointer to determine the path to the field.
There are a few types of patterns for multi-kind object references
that are currently included in the Kubernetes core resources
(EnvVarSource, ObjectReference).
Adding a section to clarify the preferred pattern for future
resources.
> When referencing another field name, indicate the name in back-quotes. Example: "must be greater than `request`".
In this sentence, we're meant to see "request" surrounded by back-quotes.
In markdown, backticks (back-quotes) are used to create a code section, and thus aren't shown. By escaping them, they are shown to the user.
Rationale: The line hasn't been updated since 2017, even though changes were still being made to the doc. We can already see the last-updated date from the git history, and if we just update it now folks will probably continue forgetting to do so in the future.
When going through the api-conventions markdown doc online, I noticed a
couple small grammar and Markdown formatting issues. This patch fixes
those up.
* Correct the link target
* Make the link description more precise
* Correct the link target - once again.
Co-Authored-By: Christoph Blecker <admin@toph.ca>
As I was reading through api-conventions.md, I noticed a couple of
broken links. This commit updates those links to resolve to their
previously linked content.
Elana Hashman
Tim Hockin
Kubernetes Prow Robot
Chris Negus
Jefftree
Khaled (Kal) Henidak
Rob Scott
Yusuke Tsutsumi
Antoine Pelisse
David Eads
Chris Couzens
Ashish Billore
bjhaid
Paul Weil
Clayton Coleman
Evan Anderson
Evan Anderson
divya-mohan0209
Michael Taufen
Eric Tune
Jay Pipes
Wojciech Sciesinski
Paul Morie
Lance Bragstad
Ivan Akulov
eduartua