We use analytics and cookies to understand site traffic. Information about your use of our site is shared with Google for that purpose. Learn more.
TODO: link to intended documentation layout. A general warning about Conway’s Law: documents will naturally tend to be distributed by team that produced them. Try to fight this, and organize documents based on where the reader will look for them. (i.e. all tutorials together, maybe with indications as to which components they use, rather than putting all serving tutorials in one place)
In some cases, the right place for a document may not be on the docs website — a blog post, documentation within a code repo, or a vendor site may be the right place. Be generous with offering to link to such locations; documents in the main documentation come with an ongoing cost of keeping up to date.
Knative attempts to
support the last 4 releases.
By default, new documentation should be written on the
main branch and then
cherry-picked to the release branches if needed. Note that the default view of
https://knative.dev/ is of the most recent release branch, which means that
main don’t show up unless explicitly cherrypicked. This also
means that documentation changes for a release should be made during the
development cycle, rather than at the last minute or after the release.
can be use to automatically pull back changes from
main to previous releases
Putting your docs in the right place
knative/docs repo contains Knative specific user-facing content
and blog content.
Contributor-focused content belongs in one of the other Knative code
Each version of the Knative docs are separated by branches in the knative/docs
main branch represents the “in active development” version
of the docs. All content in the
main branch is renders on Knative.dev under
the Pre-release menu and might not be tested nor working.
Content in all the other branches of the knative/docs repo
represent “released versions of the docs” and use the naming convention
#.# is the version of Knative to which those docs
Choosing the correct branch
It is likely that your docs contribution is either for new or changed features in the product, or for a fix or update existing content.
New or changed features: If you are adding or updating documentation for a new or changed feature, you likely want to open your PR against the
mainbranch. All pre-release content for active Knative development belongs in
Fixes and updates: If you find an issue in a past release, for example a typo or out-of-date content, you likely need to open multiple and subsequent PRs. If not a followup PR, at least add the “
cherrypicklabels” to your original PR to indicate in which of the past release that your change affects.
For example, if you find a typo in a page of the
v0.5release, then that page in the
mainbranch likely also has that typo.
To fix the typo:
Open a PR against the
Add one or more
cherrypick-#.#labels to that PR to indicate which of the past release branches should also be fixed. Generally, we only maintain the most recent numbered release.
If you want to complete the fix yourself (best practice), you then open a subsequent PR by running
git cherry-pick [COMMIT#]against the
[COMMIT#]is the commit of the PR that you merged in
Note: Depending on workload and available bandwidth, one of the Knative team members might be able to help handle the
git cherry-pickin order to push the fix into the affected release branch(es).
See a list of the available documentation versions in the
branches page of the
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.