diff --git a/contribute-to-docs/README.md b/contribute-to-docs/README.md index 216da7f33..22b848a04 100644 --- a/contribute-to-docs/README.md +++ b/contribute-to-docs/README.md @@ -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) diff --git a/contribute-to-docs/docs-release-process.md b/contribute-to-docs/docs-release-process.md new file mode 100644 index 000000000..34c7c9b88 --- /dev/null +++ b/contribute-to-docs/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`. + + ![branch](https://user-images.githubusercontent.com/35748459/87461583-804c4c80-c5c3-11ea-8105-f9b34988c9af.png) + +## 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 diff --git a/help/maintainer/_index.md b/help/maintainer/_index.md deleted file mode 100644 index c4b7e6e62..000000000 --- a/help/maintainer/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: "How-to guides for maintainers of the Knative docs repo" -linkTitle: "Maintainer guides" -weight: 50 -type: "docs" -showlandingtoc: "true" ---- diff --git a/help/maintainer/building-api-output.md b/help/maintainer/building-api-output.md deleted file mode 100644 index bfe1e9655..000000000 --- a/help/maintainer/building-api-output.md +++ /dev/null @@ -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 -``` diff --git a/help/maintainer/docs-release-process.md b/help/maintainer/docs-release-process.md deleted file mode 100644 index fce1028c8..000000000 --- a/help/maintainer/docs-release-process.md +++ /dev/null @@ -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._ - -![branch](https://user-images.githubusercontent.com/35748459/87461583-804c4c80-c5c3-11ea-8105-f9b34988c9af.png) - - -## 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`. - diff --git a/help/maintainer/docs-repo-maintanence.md b/help/maintainer/docs-repo-maintanence.md deleted file mode 100644 index f23bd9f63..000000000 --- a/help/maintainer/docs-repo-maintanence.md +++ /dev/null @@ -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