diff options
author | Evan Read <eread@gitlab.com> | 2022-06-08 04:34:33 +0300 |
---|---|---|
committer | Evan Read <eread@gitlab.com> | 2022-06-08 04:34:33 +0300 |
commit | d035f8fc0a722fe07be07259f3778d457574f104 (patch) | |
tree | f1504f035c49a6ff569f422983491b13613e089a | |
parent | db10b67b5738f5f73a644b8bf4bc5a32f23c0f4e (diff) | |
parent | 7ba84614e6a82f9ae211e041397bc97743e61a94 (diff) |
Merge branch 'aqualls-push-template-over' into 'main'
Proposal: docs release issue template
See merge request gitlab-org/gitlab-docs!2760
-rw-r--r-- | .gitlab/issue_templates/release.md | 74 | ||||
-rw-r--r-- | doc/releases.md | 22 |
2 files changed, 96 insertions, 0 deletions
diff --git a/.gitlab/issue_templates/release.md b/.gitlab/issue_templates/release.md new file mode 100644 index 00000000..2027de93 --- /dev/null +++ b/.gitlab/issue_templates/release.md @@ -0,0 +1,74 @@ +<!-- +SET TITLE TO: docs.gitlab.com release XX.ZZ (month, YYYY) +--> + +## Tasks for all releases + +Documentation [for handling the docs release](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md) is available. + +### Between the 17th and 20th of each month + +1. [ ] Cross-link to the main MR for the release post: `<add link here>` + ([Need help finding the MR?](https://gitlab.com/gitlab-com/www-gitlab-com/-/merge_requests?scope=all&state=opened&label_name%5B%5D=release%20post&label_name%5B%5D=blog%20post)) +1. [ ] Monitor the `#releases` Slack channel. When the announcement + `This is the candidate commit to be released on the 22nd` is made, it's time to begin. +1. [ ] [Create a stable branch and Docker image for release](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#create-stable-branch-and-docker-image-for-release). Do not create a merge request, just push the stable branch. + - [ ] Verify that the `image:docs-single` job passed in the new pipeline, and + created a Docker image tagged with the name of the branch. ([If it fails, how do I fix it?](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#imagedocs-latest-job-fails-due-to-broken-links)) +1. [ ] [Create a release merge request](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#create-release-merge-request) + for the new version, + which updates the version dropdown menu for the current documentation, and adds + the release to the Docker configuration. + - [ ] Mark as `Draft` and do not merge. +1. [ ] [Update the three online versions](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#update-dropdown-for-online-versions), + so they display the new release on their version dropdown menus. + +After the tasks above are complete, you don't need to do anything for a few days. + +### On the 22nd, or the first business day after + +After release post is live on the 22nd, or the next Monday morning if the release post happens on a weekend: + +1. [ ] [Merge the release merge requests](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#merge-merge-requests-and-run-docker-image-builds) + and run the necessary Docker image builds. + - [ ] Are all pipelines green? + - [ ] Merge the MRs for updates to the dropdown menus. + - [ ] Merge the docs-release merge request. + - [ ] Each merge triggers a new pipeline for each stable branch. Check + [the pipelines page](https://gitlab.com/gitlab-org/gitlab-docs/pipeline_schedules) + and wait for all the stable branch pipelines to complete before proceeding. + - [ ] Go to the [scheduled pipelines page](https://gitlab.com/gitlab-org/gitlab-docs/pipeline_schedules) + and run the Build Docker images weekly pipeline. + - [ ] In the scheduled pipeline you just started, manually run the `image:docs-latest` + job that builds the `:latest` Docker image. + - [ ] When the pipeline is complete, run the `Build docs.gitlab.com every 4 hours` + scheduled pipeline to deploy all new versions to the public documentation site. + No manually-run jobs are needed for this second pipeline. +1. [ ] After the deployment completes, open `docs.gitlab.com` in a browser. Confirm + both the latest version and the correct `pre-` version are listed in the documentation version dropdown. +1. [ ] Check all published versions of the docs to ensure they are visible and that their version menus have the latest versions. +1. [ ] In this issue, create separate _threads_ for the retrospective, and add items as they appear: + - `## :+1: What went well this release?` + - `## :-1: What didn’t go well this release?` + - `## :chart_with_upwards_trend: What can we improve going forward?` +1. [ ] Mention `@gl-docsteam` and invite them to read and participate in the retro threads. + +After the 22nd of each month: + +1. [ ] Create a release issue for the + [next TW](https://about.gitlab.com/handbook/marketing/blog/release-posts/managers/) + and assign it to them. +1. [ ] *Major releases only.* Update + [OutdatedVersions.yml](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/OutdatedVersions.yml) + with the newly-outdated version. +1. [ ] Improve this checklist. Continue moving steps from + [`releases.md`](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md) + to here until the issue template is the single source of truth and the documentation provides extra information. + +## Helpful links + +- [Troubleshooting info](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md#troubleshooting) +- [List of upcoming assignees for overall release post](https://about.gitlab.com/handbook/marketing/blog/release-posts/managers/) +- [Internal docs for handling the docs release](https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/releases.md) + +/label ~"Technical Writing" ~"type::maintenance" ~"Category:Docs Site" diff --git a/doc/releases.md b/doc/releases.md index 7ca6d9a2..46949c7b 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -230,6 +230,28 @@ and when the Charts branch is cut: - If the error happens when you create the stable branch, go to the **Pipelines** page and run a new pipeline for your branch. - If the error happens when you create the MRs to update the dropdown, return to your MR and run the pipeline again. +### image:docs-latest job fails due to broken links + +When this pipeline fails, it is usually because the `gitlab-docs` repository contains +changes to the navigation menu, but the corresponding page changes in the `gitlab` +repository didn't make it into the release. This can happen close to the cutoff for +the release. For example: + +1. On the 19th, a merge request in `gitlab` is merged, but the GitLab release doesn't include commits from that merge request. The cutoff for the + release occurred on the 18th. +1. A navigation menu item in `gitlab-docs` is also merged on the 19th. +1. The `gitlab-docs` stable branch is created on the 20th, and includes the navigation menu changes. +1. The link checker fails, because when building the Docker image, it pulls the + stable branch from `gitlab`. This branch doesn't have the new content added on + the 19th (first step), but the stable branch in `gitlab-docs` has the navigation menu changes. + +Solution: revert the navigation menu change in the `gitlab-docs` stable branch: + +1. Find the change to the navigation menu in + [the list of recently merged MRs](https://gitlab.com/gitlab-org/gitlab-docs/-/merge_requests?scope=all&state=merged) + for the `gitlab-docs` repository +1. In the **Overview** tab, select **Revert** and target the `gitlab-docs` stable branch. + ### image:docs-latest job fails with `GemNotFound` error When you start the **Build docker images weekly** scheduled pipeline and |