Skip to content

Commit dc72c6b

Browse files
vgrlnguyenalex836mchammer01
authored
[GHES Goals] Revise Docs team's GHES issue templates (#56350)
Co-authored-by: Alex Nguyen <150945400+nguyenalex836@users.noreply.github.com> Co-authored-by: mc <42146119+mchammer01@users.noreply.github.com>
1 parent 24e330c commit dc72c6b

File tree

6 files changed

+137
-547
lines changed

6 files changed

+137
-547
lines changed

‎src/ghes-releases/lib/release-templates/release-steps-0.md

Lines changed: 65 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -27,47 +27,78 @@ This issue tracks Docs work for the GA release of GHES {{ release-number }}.
2727

2828
## Instructions for triage
2929

30-
- [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
31-
- [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
30+
* [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
31+
* [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
3232

3333
<br/>
3434

3535
# Tasks
36-
- [ ] {{ release-steps-1-url }}
37-
- [ ] {{ release-steps-2-url }}
38-
- [ ] {{ release-steps-3-url }}
39-
- [ ] {{ release-steps-4-url }}
40-
- [ ] {{ release-steps-5-url }}
41-
- [ ] **Friday before the release**, notify the Docs Content first responders to not merge OpenAPI PRs until further notice.
42-
- [ ] **On the RC date**, optionally sync the search indices again (details in [previous step]({{ release-steps-1-url }}).
43-
- [ ] **On the RC date**, merge PR for RC when instructed by the GHES Releases team.
44-
- [ ] After merging PR for RC, notify the API team in [#ecosystem-api](https://github.slack.com/archives/C1042T6MS) on Slack that they can now merge "Update OpenAPI 3.x Descriptions" PRs in [`github/rest-api-description`](https://github.com/github/rest-api-description/pulls), which you blocked as part of the issue for preparing OpenAPI assets.
45-
- [ ] Notify the Docs Content first responder (`@TBD`) that they can now merge OpenAPI PRs.
46-
- [ ] To close this issue, open a PR to complete [these steps](https://github.com/github/docs-content/issues/12972#issuecomment-1947981671).
36+
* [ ] {{ release-steps-1-url }}
37+
* [ ] {{ release-steps-2-url }}
38+
* [ ] {{ release-steps-3-url }}
39+
* [ ] {{ release-steps-4-url }}
40+
* [ ] {{ release-steps-5-url }}
41+
* [ ] **Friday before the release**, notify the Docs Content first responder to not merge OpenAPI PRs until further notice.
42+
* [ ] **On the RC date**, optionally scrape the search indices again (details in [previous step]({{ release-steps-1-url }}).
43+
* [ ] **On the RC date**, to [publish the RC, complete these tasks](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#publish-release-candidate).
44+
* [ ] To close this issue, open a PR to complete [these GA tasks](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#ga-tasks).
45+
46+
## Daily tasks
47+
48+
Complete these tasks every day, up to the release of the release candidate.
49+
50+
* Maintain the megabranch by keeping it up to date with `main`, and fixing check failures
51+
* Monitor the `#ghes-3-1x-release` Slack channel for late-breaking changes
52+
* Monitor the `#tmp-docs-ghes-3-1x` Slack channel for questions and updates
53+
54+
55+
## Key deadlines
56+
57+
Optionally, use and update the following table to keep track of key deadlines.
58+
59+
<details>
60+
61+
| Date | Task | Steps | Done? ✅ |
62+
| ---- | ---- | ---- | ----- |
63+
| By **3 weeks before RC** | Create the release megabranch | [Steps]({{ release-steps-1-url }}) | |
64+
| By **3 weeks before RC** | Create a `tmp-docs-ghes-{{ release-number }}` Slack channel for docs and the GHES release team to communicate | [Example](https://github-grid.enterprise.slack.com/archives/C08T0NM9XAB) | |
65+
| By **2 weeks before RC** | Ensure there's an OpenAPI configuration for the release in `github/github`, and create and merge a PR to update `release_api_versioning_support.yaml`. | [Steps]({{ release-steps-5-url }}) | |
66+
| By **2 weeks before RC** | Create, but don't yet merge, a `github/github` PR to publish the {{ release-number }} API schema | [Steps]({{ release-steps-5-url }}) | |
67+
| By **1 week before RC on {{ release-rc-target-date-minus-7 }}** | Ensure work in the PR with the release notes is complete, request reviews for release notes, and ask GHES PM to confirm the list of [known issues](https://github.com/orgs/github/projects/7908/views/15) for the release | [Steps]({{ release-steps-2-url }}) | |
68+
| On **Friday before the RC** | Merge the `github/github` PR to publish the {{ release-number }} API schema, and notify `#eco-system-api` | [Steps]({{ release-steps-5-url }}) | |
69+
| On **Friday before the RC** | Notify docs first responder not to merge OpenAPI update PRs | In task list below | |
70+
| On **Thursday before the RC** | Merge OpenAPI data into the release [megabranch]({{ release-steps-1-url }}) | [Steps]({{ release-steps-5-url }}) | |
71+
| By **the day before the RC on {{ release-rc-target-date-minus-1 }}** | Ensure checks are passing and all assets are in the megabranch, including release notes, docs for the corresponding release work, and work for the [CodeQL]({{ release-steps-3-url }}) and [Actions Runner]({{ release-steps-4-url }}) issues in the task list below | Steps</br>* [CodeQL]({{ release-steps-3-url }}</br>* [Actions Runner]({{ release-steps-4-url }}</br> | |
72+
| On **{{ release-rc-target-date }}** | When requested, merge the megabranch PR to publish docs for the release candidate | | |
73+
| By **1 week before the GA** | Create a PR to GA the {{ release-number }} docs | [Steps]({{ release-steps-0-url }}) | |
74+
| On **{{ release-target-date }}** | When requested, merge the PR to GA the {{ release-number }} docs | [Steps]({{ release-steps-0-url }}) | |
75+
76+
</details>
4777

4878
## Resources
4979

50-
- People
51-
- Docs
52-
- DRI: `TBD`
53-
- Engineering support: `TBD`
54-
- GHES
55-
- PM: `TBD`
56-
- Releases PM: `TBD`
57-
- Releases TPM and Release Manager: `TBD`
58-
- Engineering DRI: `@{{ release-prp }}`
59-
- Videos
60-
- `TBD`
61-
- Slides
62-
- `TBD`
63-
- Docs
64-
- [Creating a GitHub Enterprise Server instance](https://github.com/github/docs-team/blob/main/contributing-to-docs/creating-a-github-enterprise-server-instance.md) in `github/docs-team`
65-
- [Internal builds](https://github.com/github/docs-team/blob/main/contributing-to-docs/creating-a-github-enterprise-server-instance.md#internal-builds), for testing pre-release RC builds
66-
- Slack
67-
- [#docs-content-enterprise](https://github.slack.com/archives/C02FQKNEN69)
68-
- [#ghes-3-14-release](`TBD`)
69-
- [#ghes-releases](https://github-grid.enterprise.slack.com/archives/C0FN5LSLR)
70-
- [#ghes-product](https://github.slack.com/archives/C02FE7F994N)
80+
* People
81+
* Docs
82+
* DRI: `TBD`
83+
* Engineering support: `TBD`
84+
* GHES
85+
* PM: `TBD`
86+
* Releases PM: `TBD`
87+
* Releases TPM and Release Manager: `TBD`
88+
* Engineering DRI: `@{{ release-prp }}`
89+
* Videos
90+
* `TBD`
91+
* Slides
92+
* `TBD`
93+
* Docs
94+
* [Creating a GitHub Enterprise Server instance](https://github.com/github/docs-team/blob/main/contributing-to-docs/docs-work/creating-a-github-enterprise-server-instance.md) in `github/docs-team`
95+
* [Internal builds](https://github.com/github/docs-team/blob/main/contributing-to-docs/docs-work/creating-a-github-enterprise-server-instance.md#internal-builds), for testing pre-release RC builds
96+
* Slack
97+
* #tmp-docs-ghes-3-1x
98+
* [#docs-driver-persona](https://github-grid.enterprise.slack.com/archives/C07KVNQ6AVA)
99+
* #ghes-3-1x-release
100+
* [#ghes-releases](https://github-grid.enterprise.slack.com/archives/C0FN5LSLR)
101+
* [#ghes](https://github-grid.enterprise.slack.com/archives/C02BJ3URF1S) and [#ghes-product](https://github.slack.com/archives/C02FE7F994N)
71102

72103
<!--
73104
This section contains the Markdown reference-style links used to populate links in the content above. Uncomment the reference links below and add the URL to the GHES release issue in `github/releases` in between the <> brackets.

‎src/ghes-releases/lib/release-templates/release-steps-1.md

Lines changed: 9 additions & 139 deletions
Original file line numberDiff line numberDiff line change
@@ -12,142 +12,12 @@ labels:
1212

1313
## Instructions for triage
1414

15-
- [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
16-
- [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
17-
18-
## Instructions for assignee
19-
20-
- [Prerequisites](#prerequisites)
21-
- [Create publication branch for a new version of GHES](#creation)
22-
- [Resolve check failures](#check-failures)
23-
- [Scrape the search indices](#scrape-search-indices)
24-
- [Maintain the publication branch](#maintenance)
25-
- [Complete preparation for the RC and publish the docset](#publication)
26-
27-
<br/>
28-
<a name="prerequisites">
29-
30-
### [👀](#prerequisites) Prerequisites
31-
32-
- Install the GitHub CLI, then authenticate.
33-
34-
- For more information about installation, see [README.md](https://github.com/cli/cli#installation) in the cli/cli repository.
35-
- To authenticate, run the `gh auth login` command. For more information about authentication, see [gh auth login](https://cli.github.com/manual/gh_auth_login) in the GitHub CLI manual.
36-
37-
- You can use either the HTTPS or SSH protocol.
38-
- Authenticate Git with your GitHub credentials.
39-
- You can use the interactive flow and sign in with a web browser.
40-
41-
<br/>
42-
<a name="creation">
43-
44-
### [🆕](#creation) Create the publication branch for a new version of GHES
45-
46-
To enable a new version of GHES on GitHub Docs, update the site's supported versions, create placeholder data, and add a banner for the release candidate (RC).
47-
48-
- [ ] In `github/docs-internal`, from `main`, create a new branch named <code>ghes-VERSION-rc</code>. For example, `ghes-3.10-rc`.
49-
50-
- To enable the new release, update the following variables defined in [`lib/enterprise-server-releases.js`](https://github.com/github/docs-internal/blob/main/src/versions/lib/enterprise-server-releases.js). The lines begin with `export const`.
51-
52-
- [ ] For `next`, iterate the value by one minor version. For example, if the value is 3.10, iterate to 3.11.
53-
54-
- [ ] For `nextNext`, iterate the value by one minor version. For example, if the version is 3.11, iterate to 3.12.
55-
56-
- [ ] For `supported`, prepend the new version. For example, if the array contains 3.9, 3.8, 3.7, and 3.6, add 3.10:
57-
58-
```js
59-
export const supported = ["3.10", "3.9", "3.8", "3.7", "3.6"];
60-
```
61-
62-
- [ ] For `releaseCandidate`, change the variable definition from `null` to the release version. For example, if the release version is 3.10:
63-
64-
```js
65-
export const releaseCandidate = "3.10";
66-
```
67-
68-
- [ ] Add and commit the changes.
69-
70-
- Create placeholder data files for release notes and content from automated pipelines.
71-
72-
- [ ] Run the following script.
73-
74-
```shell
75-
npm run deprecate-ghes -- pipelines
76-
```
77-
78-
- [ ] Add and commit the changes.
79-
80-
- [ ] Optionally, on your workstation, run the local development environment for GitHub Docs and verify that the new GHES version is enabled. See [About versions of GitHub Docs](https://docs.github.com/get-started/learning-about-github/about-versions-of-github-docs).
81-
82-
- [ ] Push your changes.
83-
84-
- [ ] Create a PR. For the body, copy the contents of the body comment for the [previous release](https://github.com/github/docs-internal/pull/44684), modifying it to reflect this release.
85-
86-
- [ ] Link your PR to this issue. See [Linking a pull request to an issue](https://docs.github.com/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#manually-linking-a-pull-request-to-an-issue-using-the-pull-request-sidebar).
87-
88-
<br/>
89-
<a name="check-failures">
90-
91-
### [🚨](#check-failures) Resolve check failures
92-
93-
After you create the publication PR, ensure that the checks pass as soon as possible. If you experience a check failure that isn't listed below, contact Docs Engineering for support.
94-
95-
#### Link Checker: On PR / check-links (pull_request)
96-
97-
Our link checker validates links the site. If links are broken immediately after creation of your publication PR, the broken link was missed upon introduction because it's within content that did not yet render anywhere on the site. There are two common reasons for these failures.
98-
99-
- We mentioned GitHub.com-only features within GHES articles that are also versioned for FPT or GHEC. See [Enterprise products](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/writing-for-enterprise/products.md#feature-availability) in the Enterprise focus area docs.
100-
- We linked from content outside of the API or webhooks docs to API or webhook docs that have not yet been generated and published from the OpenAPI schema in github/github.
101-
102-
If you aren't familiar with the content with the broken link, consult the DRI for the content's focus area. See the [README](https://github.com/github/docs-content/blob/main/focus-areas/README.md) in `github/docs-content`.
103-
104-
For broken links due to in-progress work elsewhere in the docs, you can comment out problematic versioning temporarily by:
105-
106-
- using {% raw %}`{% comment %}`{% endraw %} tags in Liquid or
107-
- prepending `#` in YAML front matter.
108-
109-
If you comment out versioning, explain the temporary change in a comment on the **Files changed** tab, and track the necessary updates PR's body. After the necessary changes are in `main`, uncomment the versioned content.
110-
111-
For content from the OpenAPI schema, note the affected content with broken links in the PR's body.
112-
113-
<a name="rest-pull-request">
114-
115-
<br/>
116-
117-
<a name="scrape-search-indices">
118-
119-
### [🔎](#scrape-search-indices) Scrape the search indices
120-
121-
1. Go to the [`index-general-search.yml` workflow](https://github.com/github/docs-internal/actions/workflows/index-general-search.yml)
122-
1. Click on the **Run workflow** drop down and set the following parameters:
123-
- `Branch:` set to the name of the publication branch
124-
- `Version` set to the version you're publishing (e.g., `ghes-3.12` if you're publishing GHES 3.12)
125-
- `Languages` left as default (blank, all languages. If time is a concern, can also set to just `en` and wait for the workflow to automatically include the other languages in later runs)
126-
1. Click **Run workflow** and wait for the workflow to finish running, which can take up to 30 minutes.
127-
128-
_Note_: After performing these steps, search indices will be automatically updated when the workflow runs on `main`, once every 4 hours. However, it will not do so until you first complete the steps above which will manually create a search index for the new release.
129-
130-
<a name="maintenance">
131-
132-
### [🔁](#maintenance) Maintain the publication branch
133-
134-
After your publication PR's are passing, complete the following maintenance **daily**.
135-
136-
1. In your clone of `github/docs-internal`, ensure the environment is clean and there are no pending changes.
137-
138-
1. Check out `main`, then pull the latest changes.
139-
140-
1. Check out your publication branch, <code>ghes-VERSION-rc</code>, then merge changes from `main`.
141-
142-
1. Push the changes.
143-
144-
1. If new check failures arise, refer to "Addressing check failures" above.
145-
146-
1. If merge conflicts arise, resolve them. If you're not sure how to resolve the conflict, consult the DRI for the content's focus area. See the [README](https://github.com/github/docs-content/blob/main/focus-areas/README.md) in `github/docs-content`.
147-
148-
<br/>
149-
<a name="publication">
150-
151-
### [🚢](#publication) Complete preparation for the RC and publish the docset
152-
153-
Continue the tasks in {{ release-steps-0-url }}. Leave this issue open until you merge the publication PR.
15+
* [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
16+
* [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
17+
18+
# Tasks
19+
* [ ] [Create publication branch for a new version of GHES](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#11-create-the-publication-branch)
20+
* [ ] [Resolve check failures](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#12-resolve-check-failures)
21+
* [ ] [Scrape the search indices](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#13-scrape-the-search-indices)
22+
* [ ] [Maintain the publication branch](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#14-maintain-the-publication-branch)
23+
* [ ] Continue the tasks in {{ release-steps-0-url }} to complete preparation for the RC and [publish the docset](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#publish-release-candidate). Leave this issue open until you merge the publication PR.

0 commit comments

Comments
 (0)