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)
|
- [Word and phrase list](style-guide/word-and-phrase-list.md)
|
||||||
- [Content re-use](style-guide/content-reuse.md)
|
- [Content re-use](style-guide/content-reuse.md)
|
||||||
- Using shortcodes (TBD)
|
- 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