mirror of https://github.com/knative/docs.git
Move docs release process (#4717)
* Move docs release process * Fix typo
This commit is contained in:
Samia Nneji
GitHub
parent
57231f3c5a
commit
fc4ba73d43
|
|
@ -39,3 +39,9 @@ If you notice gaps in the style guide or have queries, please post in [the Docs
|
|||
- [Word and phrase list](style-guide/word-and-phrase-list.md)
|
||||
- [Content re-use](style-guide/content-reuse.md)
|
||||
- Using shortcodes (TBD)
|
||||
|
||||
## Maintainer guides
|
||||
|
||||
How-to guides for maintainers of the Knative docs repo and website:
|
||||
|
||||
- [Releasing a new version of the Knative documentation](docs-release-process.md)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,58 @@
|
|||
# Releasing a new version of the Knative documentation
|
||||
|
||||
This document describes how to perform a docs release. In general, this should
|
||||
be done by one of the release managers in the list at
|
||||
https://github.com/knative/release.
|
||||
|
||||
To release a new version of the docs you must:
|
||||
|
||||
1. [Check dependencies](#check-dependencies)
|
||||
1. [Create a release branch](#create-a-release-branch)
|
||||
1. [Generate the new docs version](#generate-the-new-docs-version)
|
||||
|
||||
## Check dependencies
|
||||
|
||||
You cannot release a new version of the docs until the Knative components have
|
||||
built their new release.
|
||||
This is because the website references these releases in various locations.
|
||||
|
||||
Check the following components for the new release:
|
||||
|
||||
* [client](https://github.com/knative/client/releases/)
|
||||
* [eventing](https://github.com/knative/eventing/releases/)
|
||||
* [operator](https://github.com/knative/operator/releases/)
|
||||
* [serving](https://github.com/knative/serving/releases/)
|
||||
|
||||
## Create a release branch
|
||||
|
||||
1. Check on the `#docs` Slack channel to make sure the release is ready.
|
||||
_In the future, we should automate this so the check isn't needed._
|
||||
|
||||
1. Using the GitHub UI, create a `release-X.Y` branch based on `main`.
|
||||
|
||||
|
||||
|
||||
## Generate the new docs version
|
||||
|
||||
To generate the new version of the docs, you must update the [`hack/build.sh`](../hack/build.sh)
|
||||
script in the main branch to reference the new release.
|
||||
|
||||
We keep the last 4 releases available per [our support window](https://github.com/knative/community/blob/main/mechanics/RELEASE-VERSIONING-PRINCIPLES.md#knative-community-support-window-principle).
|
||||
|
||||
To generate the new docs version:
|
||||
|
||||
1. In `hack/build.sh` on the main branch, update `VERSIONS` and `RELEASE_BRANCHES`
|
||||
to include the new version, and remove the oldest. Order matters, most recent first.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
VERSIONS=("1.2" "1.1" "1.0" "0.26")
|
||||
RELEASE_BRANCHES=("knative-v1.2.0" "knative-v1.1.0" "knative-v1.0.0" "v0.26.0")
|
||||
```
|
||||
|
||||
1. PR the result to main.
|
||||
|
||||
## How GitHub and Netlify are hooked up
|
||||
|
||||
TODO: add information about how the docs are built and served using Netlify
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
---
|
||||
title: "How-to guides for maintainers of the Knative docs repo"
|
||||
linkTitle: "Maintainer guides"
|
||||
weight: 50
|
||||
type: "docs"
|
||||
showlandingtoc: "true"
|
||||
---
|
||||
|
|
@ -1,138 +0,0 @@
|
|||
---
|
||||
title: "Building API docs from the Knative component repos"
|
||||
linkTitle: "Generating API docs"
|
||||
weight: 85
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
The Knative API docs are built from the code in the Knative
|
||||
[Serving](https://github.com/knative/serving/) and
|
||||
[Eventing](https://github.com/knative/eventing/) repos.
|
||||
|
||||
New API docs are generated and then published at
|
||||
https://www.knative.dev/docs/reference/api for every release.
|
||||
|
||||
### Source files
|
||||
|
||||
API source files are located at:
|
||||
|
||||
- [Serving API](../../../reference/api/serving.md)
|
||||
- [Eventing API](../../../reference/api/eventing/eventing.md)
|
||||
|
||||
## Updating API Reference docs (for Knative maintainers)
|
||||
|
||||
The Knative API reference documentation is manually generated using the
|
||||
[`gen-api-reference-docs.sh`](../../../hack/) tool. If you need to generate a new
|
||||
version of the API docs for a recent update or for a new release, you can use
|
||||
the following steps.
|
||||
|
||||
To learn more about the tool, see the
|
||||
[gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs)
|
||||
reference page.
|
||||
|
||||
### Before you begin
|
||||
|
||||
You must meet the following requirements to run the `gen-api-reference-docs.sh`
|
||||
tool:
|
||||
|
||||
- You need the following software installed:
|
||||
- [`git`](https://git-scm.com/download/)
|
||||
- [`go` version 1.11+](https://golang.org/dl/)
|
||||
- Clone [knative/docs](https://github.com/knative/docs) locally. For example:
|
||||
`git clone git@github.com:knative/docs.git`
|
||||
|
||||
### Generating the API
|
||||
|
||||
To generate a version of the API:
|
||||
|
||||
1. Ensure that your `GOPATH` is empty. The `gen-api-reference-docs.sh` script
|
||||
will result in the `GOPATH should not be set` error if your `GOPATH` is
|
||||
configured. You view the value by running the following command:
|
||||
|
||||
```
|
||||
echo $GOPATH
|
||||
```
|
||||
|
||||
If your `GOPATH` is already configured, temporarily clear the `GOPATH` value
|
||||
by running the following command:
|
||||
|
||||
```
|
||||
export GOPATH=""
|
||||
```
|
||||
|
||||
1. Locate the commits or tags that correspond to the version of the API that you
|
||||
want to generate:
|
||||
|
||||
- [Serving](https://github.com/knative/serving/releases/)
|
||||
- [Eventing](https://github.com/knative/eventing/releases/)
|
||||
|
||||
1. To run the `gen-api-reference-docs.sh` command from the `hack` directory, you
|
||||
specify the commits or tags for each of the corresponding Knative component
|
||||
variables (`KNATIVE_[component_name]_COMMIT`):
|
||||
|
||||
```
|
||||
cd hack
|
||||
|
||||
KNATIVE_SERVING_COMMIT=[commit_or_tag] \
|
||||
KNATIVE_EVENTING_COMMIT=[commit_or_tag] \
|
||||
./gen-api-reference-docs.sh
|
||||
```
|
||||
|
||||
where `[commit_or_tag]` is the commit or tag in the specific repo that
|
||||
represents the version of the API that you want to generate. Also see the
|
||||
[example](#example) below.
|
||||
|
||||
**Result**
|
||||
|
||||
The `gen-api-reference-docs.sh` tool generates the API in a `tmp` folder.
|
||||
After a successful build, the tool automatically opens that folder in the
|
||||
`tmp` directory.
|
||||
|
||||
If the script fails, there are a couple possible causes.
|
||||
|
||||
* If you get the
|
||||
`F1116 15:21:23.549503 63473 main.go:129] no API packages found in ./pkg/apis`
|
||||
error, check if a new version of the script is available:
|
||||
https://github.com/ahmetb/gen-crd-api-reference-docs/tags
|
||||
|
||||
The script is kept up-to-date with changes that go into the Kubernetes API.
|
||||
As Knative adds support for those APIs, you might need to make sure the
|
||||
corresponding
|
||||
[script `gen-crd-api-reference-docs` version](https://github.com/knative/docs/blob/main/hack/gen-api-reference-docs.sh#L26)
|
||||
is used.
|
||||
|
||||
* If you get the
|
||||
`F0807 13:58:20.621526 168834 main.go:444] type invalid type has kind=Unsupported which is unhandled`
|
||||
error, the import target might have moved. There might be other causes for
|
||||
that error but view [#2054](https://github.com/knative/docs/pull/2054)
|
||||
(and the linked Issues) for details about how we handled that error
|
||||
in the past.
|
||||
|
||||
1. Copy the generated API files into the `docs/reference` directory of your
|
||||
knative/docs clone.
|
||||
|
||||
1. The linter now fails for content with trailing whitespaces. Use a tool of
|
||||
your choice to remove all trailing whitespace. For example, search for and
|
||||
remove: `\s+$`
|
||||
|
||||
You can now perform the necessary steps to open a PR, complete a review, and
|
||||
merge the new API files into the appropriate branch of the `knative/docs` repo.
|
||||
See the [contributor flow](https://github.com/knative/community/blob/main/docs/DOCS-CONTRIBUTING.md) for details
|
||||
about requesting changes in the `knative/docs` repo.
|
||||
|
||||
### Example
|
||||
|
||||
To build a set of Knative API docs for v0.18, you can use the `v0.18.0` the tags
|
||||
from each of the Knative component repositories, like
|
||||
[Serving v0.18.0](https://github.com/knative/serving/tree/v0.18.0). If you want to
|
||||
use a commit for Serving v0.18.0, you would use
|
||||
[850b7c](https://github.com/knative/serving/commit/850b7cca7d7701b052420a030f2308d19938d45e).
|
||||
|
||||
Using tags from each repo, you would run the following command to generate the
|
||||
v0.18.0 API source files:
|
||||
|
||||
```
|
||||
KNATIVE_SERVING_COMMIT=v0.18.0 \
|
||||
KNATIVE_EVENTING_COMMIT=v0.18.0 \
|
||||
./gen-api-reference-docs.sh
|
||||
```
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
---
|
||||
title: "Releasing a version of the Knative documentation"
|
||||
linkTitle: "Release process"
|
||||
weight: 75
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
This document describes how to perform a docs release. In general, this should
|
||||
be done by one of the release managers in the list at
|
||||
https://github.com/knative/release.
|
||||
|
||||
## Check Eventing, Serving, Client, and Operator
|
||||
|
||||
Have they all built releases (since the website references these release pages
|
||||
in various locations)?
|
||||
|
||||
* [client](https://github.com/knative/client/releases/)
|
||||
* [eventing](https://github.com/knative/eventing/releases/)
|
||||
* [operator](https://github.com/knative/operator/releases/)
|
||||
* [serving](https://github.com/knative/serving/releases/)
|
||||
|
||||
## Create a release branch
|
||||
|
||||
Using the GitHub UI, create a `release-X.Y` branch based on `main`. **Check on
|
||||
the `#docs` channel to make sure the release is ready.** _In the future, we
|
||||
should automate this so the check isn't needed._
|
||||
|
||||
|
||||
|
||||
|
||||
## Update the main branch to reference the release
|
||||
|
||||
### `hack/build.sh`
|
||||
|
||||
Find the references to the previous release number and update the lines to
|
||||
include the new release number as well. We keep the last 4 releases available
|
||||
per [our support
|
||||
window](https://github.com/knative/community/blob/main/mechanics/RELEASE-VERSIONING-PRINCIPLES.md#knative-community-support-window-principle),
|
||||
so clean up old versions at the end of the list when there will be more than 4.
|
||||
|
||||
Until the old hugo configuration has been aged out (after release 0.27), it's
|
||||
best to send these PRs to @julz to double-check. You'll also want to remove the
|
||||
appropriate directory of hugo content under `archived/vX.Y-docs` for the oldest
|
||||
version, i.e. 0.26 release removed the `archived/v0.22-docs`.
|
||||
|
||||
|
|
@ -1,118 +0,0 @@
|
|||
---
|
||||
title: "Maintaining the Knative doc and website repos"
|
||||
linkTitle: "Repo maintenance"
|
||||
weight: 100
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
## How GitHub and Netlify are hooked up
|
||||
|
||||
https://knative.dev/ is built and served by [Netlify](https://netlify.com/) on their platform.
|
||||
When debugging issues on the website, it can be useful to understand what Netlify is doing (as we've
|
||||
configured it).
|
||||
|
||||
Generally, Netlify runs Hugo/Docsy builds and publishes everything that gets merged into the knative/docs and knative/website repos
|
||||
(anything in knative/community will get picked up when either of the other two repos trigger a build).
|
||||
|
||||
The builds are triggered are through [GitHub webhooks](https://docs.github.com/en/developers/webhooks-and-events/webhook-events-and-payloads).
|
||||
There are two webhooks sent from knative/docs that are configured to inidicate that they were sent from knative/website:
|
||||
|
||||
* One that triggers a "production" build - Any PR that gets merged. (Webhook payload - /website `main` branch)
|
||||
* One that triggers a "preview" build - Any PR action other than a merge (ie. commit, comment, label, etc). (Webhook payload - /website `staging` branch)
|
||||
|
||||
All of our builds (and build logs) are shown here: https://app.netlify.com/sites/knative/deploys (in the order of recent to past)
|
||||
|
||||
|
||||
## Keep knative/website 'staging' with 'main' in sync
|
||||
|
||||
Both branches are identical but all PRs get merged into `main`. They can drift
|
||||
apart since staging only builds the PR owners fork and branch. It's best to keep
|
||||
in sync to avoid dealing with merge conflicts.
|
||||
|
||||
Two branches are used only to align with and use Netlify's built-in continuous
|
||||
site deployment configuration:
|
||||
|
||||
`main` - triggered when any PR gets pushed into knative/docs
|
||||
`staging` - triggered for any event (other than 'push') in a PR
|
||||
|
||||
Assuming that you have a local fork of the knative/website `staging` branch:
|
||||
|
||||
1. Copy `main` into `staging`, for example:
|
||||
|
||||
* Merge:
|
||||
|
||||
```
|
||||
git checkout staging
|
||||
git pull upstream main
|
||||
git push origin staging
|
||||
```
|
||||
|
||||
* Hard reset and force push also works:
|
||||
|
||||
```
|
||||
git checkout staging
|
||||
git reset --hard upstream/main
|
||||
git push -f origin staging
|
||||
```
|
||||
|
||||
1. Open a PR and merge into knative/website staging
|
||||
|
||||
|
||||
## Check for and keep Hugo and Docsy up-to-date:
|
||||
|
||||
- Hugo releases: Update local versions if you use scripts/localbuild.sh. Update https://github.com/knative/website/blob/main/netlify.toml#L5
|
||||
- Docsy releases: https://www.docsy.dev/docs/updating/
|
||||
|
||||
## Other notes
|
||||
|
||||
- How to hide files from the build: https://github.com/knative/website/blob/main/config/_default/config.toml#L12
|
||||
|
||||
Account info (include current owners):
|
||||
|
||||
- Netlify
|
||||
|
||||
- Google Domains
|
||||
|
||||
- Google Analytics
|
||||
|
||||
- Google Search
|
||||
|
||||
### Website infrastructure:
|
||||
|
||||
- Hugo - static site engine
|
||||
- Includes a version of Bootstrap
|
||||
- Docsy - Hugo template for technical documentation
|
||||
- [Markdown processor info](https://gohugo.io/getting-started/configuration-markup/)
|
||||
- Netlify - continuous build
|
||||
- GitHub repos
|
||||
- knative/docs repo
|
||||
- knative/website repo
|
||||
- knative/community repo
|
||||
|
||||
### Integration tests
|
||||
|
||||
- Link checking
|
||||
|
||||
- Whitespace lint
|
||||
|
||||
## Todos
|
||||
|
||||
Other "docs contributor" related items:
|
||||
|
||||
- [ ] https://github.com/knative/docs/issues/1032
|
||||
- [ ] https://github.com/knative/docs/issues/1009
|
||||
- [ ] https://github.com/knative/docs/issues/1282
|
||||
- [ ] https://github.com/knative/docs/issues/1239
|
||||
- [ ] https://github.com/knative/docs/issues/1344
|
||||
|
||||
Recent items:
|
||||
|
||||
[ ] Auto PR staging: https://app.netlify.com/sites/knative/deploys
|
||||
|
||||
[ ] How Prow chooses reviewers: https://github.com/kubernetes/test-infra/tree/master/prow/plugins/approve/approvers#blunderbuss-selection-mechanism
|
||||
|
||||
[ ] GitHub troubleshooting: https://github.com/knative/docs/issues/2755
|
||||
|
||||
Build scripts:
|
||||
|
||||
- How cross linking between /docs and /community works
|
||||
Loading…
Reference in New Issue