[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>
This commit is contained in:
Vanessa
@@ -27,47 +27,78 @@ This issue tracks Docs work for the GA release of GHES {{ release-number }}.
|
||||
|
||||
## Instructions for triage
|
||||
|
||||
- [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
|
||||
- [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
|
||||
* [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
|
||||
* [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
|
||||
|
||||
<br/>
|
||||
|
||||
# Tasks
|
||||
- [ ] {{ release-steps-1-url }}
|
||||
- [ ] {{ release-steps-2-url }}
|
||||
- [ ] {{ release-steps-3-url }}
|
||||
- [ ] {{ release-steps-4-url }}
|
||||
- [ ] {{ release-steps-5-url }}
|
||||
- [ ] **Friday before the release**, notify the Docs Content first responders to not merge OpenAPI PRs until further notice.
|
||||
- [ ] **On the RC date**, optionally sync the search indices again (details in [previous step]({{ release-steps-1-url }}).
|
||||
- [ ] **On the RC date**, merge PR for RC when instructed by the GHES Releases team.
|
||||
- [ ] 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.
|
||||
- [ ] Notify the Docs Content first responder (`@TBD`) that they can now merge OpenAPI PRs.
|
||||
- [ ] To close this issue, open a PR to complete [these steps](https://github.com/github/docs-content/issues/12972#issuecomment-1947981671).
|
||||
* [ ] {{ release-steps-1-url }}
|
||||
* [ ] {{ release-steps-2-url }}
|
||||
* [ ] {{ release-steps-3-url }}
|
||||
* [ ] {{ release-steps-4-url }}
|
||||
* [ ] {{ release-steps-5-url }}
|
||||
* [ ] **Friday before the release**, notify the Docs Content first responder to not merge OpenAPI PRs until further notice.
|
||||
* [ ] **On the RC date**, optionally scrape the search indices again (details in [previous step]({{ release-steps-1-url }}).
|
||||
* [ ] **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).
|
||||
* [ ] 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).
|
||||
|
||||
## Daily tasks
|
||||
|
||||
Complete these tasks every day, up to the release of the release candidate.
|
||||
|
||||
* Maintain the megabranch by keeping it up to date with `main`, and fixing check failures
|
||||
* Monitor the `#ghes-3-1x-release` Slack channel for late-breaking changes
|
||||
* Monitor the `#tmp-docs-ghes-3-1x` Slack channel for questions and updates
|
||||
|
||||
|
||||
## Key deadlines
|
||||
|
||||
Optionally, use and update the following table to keep track of key deadlines.
|
||||
|
||||
<details>
|
||||
|
||||
| Date | Task | Steps | Done? ✅ |
|
||||
| ---- | ---- | ---- | ----- |
|
||||
| By **3 weeks before RC** | Create the release megabranch | [Steps]({{ release-steps-1-url }}) | |
|
||||
| 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) | |
|
||||
| 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 }}) | |
|
||||
| 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 }}) | |
|
||||
| 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 }}) | |
|
||||
| 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 }}) | |
|
||||
| On **Friday before the RC** | Notify docs first responder not to merge OpenAPI update PRs | In task list below | |
|
||||
| On **Thursday before the RC** | Merge OpenAPI data into the release [megabranch]({{ release-steps-1-url }}) | [Steps]({{ release-steps-5-url }}) | |
|
||||
| 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> | |
|
||||
| On **{{ release-rc-target-date }}** | When requested, merge the megabranch PR to publish docs for the release candidate | | |
|
||||
| By **1 week before the GA** | Create a PR to GA the {{ release-number }} docs | [Steps]({{ release-steps-0-url }}) | |
|
||||
| On **{{ release-target-date }}** | When requested, merge the PR to GA the {{ release-number }} docs | [Steps]({{ release-steps-0-url }}) | |
|
||||
|
||||
</details>
|
||||
|
||||
## Resources
|
||||
|
||||
- People
|
||||
- Docs
|
||||
- DRI: `TBD`
|
||||
- Engineering support: `TBD`
|
||||
- GHES
|
||||
- PM: `TBD`
|
||||
- Releases PM: `TBD`
|
||||
- Releases TPM and Release Manager: `TBD`
|
||||
- Engineering DRI: `@{{ release-prp }}`
|
||||
- Videos
|
||||
- `TBD`
|
||||
- Slides
|
||||
- `TBD`
|
||||
- Docs
|
||||
- [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`
|
||||
- [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
|
||||
- Slack
|
||||
- [#docs-content-enterprise](https://github.slack.com/archives/C02FQKNEN69)
|
||||
- [#ghes-3-14-release](`TBD`)
|
||||
- [#ghes-releases](https://github-grid.enterprise.slack.com/archives/C0FN5LSLR)
|
||||
- [#ghes-product](https://github.slack.com/archives/C02FE7F994N)
|
||||
* People
|
||||
* Docs
|
||||
* DRI: `TBD`
|
||||
* Engineering support: `TBD`
|
||||
* GHES
|
||||
* PM: `TBD`
|
||||
* Releases PM: `TBD`
|
||||
* Releases TPM and Release Manager: `TBD`
|
||||
* Engineering DRI: `@{{ release-prp }}`
|
||||
* Videos
|
||||
* `TBD`
|
||||
* Slides
|
||||
* `TBD`
|
||||
* Docs
|
||||
* [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`
|
||||
* [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
|
||||
* Slack
|
||||
* #tmp-docs-ghes-3-1x
|
||||
* [#docs-driver-persona](https://github-grid.enterprise.slack.com/archives/C07KVNQ6AVA)
|
||||
* #ghes-3-1x-release
|
||||
* [#ghes-releases](https://github-grid.enterprise.slack.com/archives/C0FN5LSLR)
|
||||
* [#ghes](https://github-grid.enterprise.slack.com/archives/C02BJ3URF1S) and [#ghes-product](https://github.slack.com/archives/C02FE7F994N)
|
||||
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -12,142 +12,12 @@ labels:
|
||||
|
||||
## Instructions for triage
|
||||
|
||||
- [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
|
||||
- [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
|
||||
* [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
|
||||
* [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
|
||||
|
||||
## Instructions for assignee
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Create publication branch for a new version of GHES](#creation)
|
||||
- [Resolve check failures](#check-failures)
|
||||
- [Scrape the search indices](#scrape-search-indices)
|
||||
- [Maintain the publication branch](#maintenance)
|
||||
- [Complete preparation for the RC and publish the docset](#publication)
|
||||
|
||||
<br/>
|
||||
<a name="prerequisites">
|
||||
|
||||
### [👀](#prerequisites) Prerequisites
|
||||
|
||||
- Install the GitHub CLI, then authenticate.
|
||||
|
||||
- For more information about installation, see [README.md](https://github.com/cli/cli#installation) in the cli/cli repository.
|
||||
- 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.
|
||||
|
||||
- You can use either the HTTPS or SSH protocol.
|
||||
- Authenticate Git with your GitHub credentials.
|
||||
- You can use the interactive flow and sign in with a web browser.
|
||||
|
||||
<br/>
|
||||
<a name="creation">
|
||||
|
||||
### [🆕](#creation) Create the publication branch for a new version of GHES
|
||||
|
||||
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).
|
||||
|
||||
- [ ] In `github/docs-internal`, from `main`, create a new branch named <code>ghes-VERSION-rc</code>. For example, `ghes-3.10-rc`.
|
||||
|
||||
- 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`.
|
||||
|
||||
- [ ] For `next`, iterate the value by one minor version. For example, if the value is 3.10, iterate to 3.11.
|
||||
|
||||
- [ ] For `nextNext`, iterate the value by one minor version. For example, if the version is 3.11, iterate to 3.12.
|
||||
|
||||
- [ ] For `supported`, prepend the new version. For example, if the array contains 3.9, 3.8, 3.7, and 3.6, add 3.10:
|
||||
|
||||
```js
|
||||
export const supported = ["3.10", "3.9", "3.8", "3.7", "3.6"];
|
||||
```
|
||||
|
||||
- [ ] For `releaseCandidate`, change the variable definition from `null` to the release version. For example, if the release version is 3.10:
|
||||
|
||||
```js
|
||||
export const releaseCandidate = "3.10";
|
||||
```
|
||||
|
||||
- [ ] Add and commit the changes.
|
||||
|
||||
- Create placeholder data files for release notes and content from automated pipelines.
|
||||
|
||||
- [ ] Run the following script.
|
||||
|
||||
```shell
|
||||
npm run deprecate-ghes -- pipelines
|
||||
```
|
||||
|
||||
- [ ] Add and commit the changes.
|
||||
|
||||
- [ ] 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).
|
||||
|
||||
- [ ] Push your changes.
|
||||
|
||||
- [ ] 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.
|
||||
|
||||
- [ ] 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).
|
||||
|
||||
<br/>
|
||||
<a name="check-failures">
|
||||
|
||||
### [🚨](#check-failures) Resolve check failures
|
||||
|
||||
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.
|
||||
|
||||
#### Link Checker: On PR / check-links (pull_request)
|
||||
|
||||
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.
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
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`.
|
||||
|
||||
For broken links due to in-progress work elsewhere in the docs, you can comment out problematic versioning temporarily by:
|
||||
|
||||
- using {% raw %}`{% comment %}`{% endraw %} tags in Liquid or
|
||||
- prepending `#` in YAML front matter.
|
||||
|
||||
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.
|
||||
|
||||
For content from the OpenAPI schema, note the affected content with broken links in the PR's body.
|
||||
|
||||
<a name="rest-pull-request">
|
||||
|
||||
<br/>
|
||||
|
||||
<a name="scrape-search-indices">
|
||||
|
||||
### [🔎](#scrape-search-indices) Scrape the search indices
|
||||
|
||||
1. Go to the [`index-general-search.yml` workflow](https://github.com/github/docs-internal/actions/workflows/index-general-search.yml)
|
||||
1. Click on the **Run workflow** drop down and set the following parameters:
|
||||
- `Branch:` set to the name of the publication branch
|
||||
- `Version` set to the version you're publishing (e.g., `ghes-3.12` if you're publishing GHES 3.12)
|
||||
- `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)
|
||||
1. Click **Run workflow** and wait for the workflow to finish running, which can take up to 30 minutes.
|
||||
|
||||
_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.
|
||||
|
||||
<a name="maintenance">
|
||||
|
||||
### [🔁](#maintenance) Maintain the publication branch
|
||||
|
||||
After your publication PR's are passing, complete the following maintenance **daily**.
|
||||
|
||||
1. In your clone of `github/docs-internal`, ensure the environment is clean and there are no pending changes.
|
||||
|
||||
1. Check out `main`, then pull the latest changes.
|
||||
|
||||
1. Check out your publication branch, <code>ghes-VERSION-rc</code>, then merge changes from `main`.
|
||||
|
||||
1. Push the changes.
|
||||
|
||||
1. If new check failures arise, refer to "Addressing check failures" above.
|
||||
|
||||
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`.
|
||||
|
||||
<br/>
|
||||
<a name="publication">
|
||||
|
||||
### [🚢](#publication) Complete preparation for the RC and publish the docset
|
||||
|
||||
Continue the tasks in {{ release-steps-0-url }}. Leave this issue open until you merge the publication PR.
|
||||
# Tasks
|
||||
* [ ] [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)
|
||||
* [ ] [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)
|
||||
* [ ] [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)
|
||||
* [ ] [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)
|
||||
* [ ] 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.
|
||||
|
||||
@@ -12,191 +12,42 @@ labels:
|
||||
|
||||
## Instructions for triage
|
||||
|
||||
- [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
|
||||
- [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
|
||||
|
||||
## Instructions for assignee
|
||||
|
||||
To prepare for a GHES RC, you will:
|
||||
- monitor for late-breaking content changes
|
||||
- validate the content being published
|
||||
- gather and edit release notes
|
||||
- share release notes with stakeholders
|
||||
|
||||
- [Track content work and progress toward final builds](#tracking)
|
||||
- [Populate the Release Tracker's "GHES Docs" view](#population)
|
||||
- [Validate docs needs for each of the release's changes](#validation)
|
||||
- [Correct erroneous versioning](#versioning)
|
||||
- [Gather and edit release notes](#release-note-preparation)
|
||||
- [Finalize and share release notes](#release-note-finalization)
|
||||
- [Complete preparation for the RC and publish the docset](#publication)
|
||||
|
||||
<br/>
|
||||
<a name="tracking">
|
||||
|
||||
### [🔁](#tracking) Track content work and progress to final builds
|
||||
|
||||
Each day, review [GHES release slack channel][ghes-release-slack-channel-link] on Slack for any potential late-breaking content changes.
|
||||
|
||||
- Most conversation is operational and relates to preparation of the release builds, with no docs impact.
|
||||
- Typically, at this phase, any content changes would relate to content in the [Enterprise administrators](https://docs.github.com/en/enterprise-server/admin) docset. If you see discussion about end-user features, investigate further.
|
||||
- If you're uncertain whether the conversation relates to changes that could affect the docs, ask the following questions.
|
||||
- [Which audience](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/writing-for-enterprise/audiences.md) is affected?
|
||||
- Is there any change in behavior or functionality that might affect the public docs? For example, is a feature pulled from the release?
|
||||
- If the audience needs to do something because of some bug or issue that will ship in the RC, what should they do?
|
||||
- Work with the stakeholder to determine whether new [docs for a known issue](https://github.com/github/docs-internal/blob/main/contributing/content-model.md#known-issues), a new [release note](https://github.com/github/docs-internal/blob/main/contributing/content-model.md#release-notes), or both are necessary.
|
||||
|
||||
<br/>
|
||||
<a name="population">
|
||||
|
||||
### [🔍](#population) Populate the Release Tracker's "GHES Docs" view
|
||||
|
||||
To begin validation of content for the release, populate data in the Release Tracker project for each github/releases issue that comprises the release. You'll use this view as a dashboard as you prepare content.
|
||||
|
||||
- [ ] In the Release Tracker project's [GHES Docs][ghes-release-tracker-project-board-link] view, ensure that the label for filtering releases corresponds with the version of GHES that you're preparing content for.
|
||||
|
||||
- Optionally, if the view doesn't already reflect this, update the view and save the changes.
|
||||
|
||||
- For each item in the view, complete the following tasks.
|
||||
|
||||
1. Update the item's "Docs Content issue" field with a link to the release's issue in `github/docs-content`.
|
||||
|
||||
- In the issue, confirm the status of docs for the release. Check for a `docs`, `docs - NA`, or `docs - TBD` label.
|
||||
- If the issue has a corresponding github/docs-content issue, add the URL to the field. If the issue did not need docs, set the value of the field to "N/A".
|
||||
|
||||
1. Update the item's "Release note source" field with a link to source material for the release note.
|
||||
|
||||
- In the issue, search for a GitHub Blog or Changelog post. Posts originate from PRs in the github/blog repository, so you may be able to locate the PR by searching the issue's page for "blog#".
|
||||
- Sometimes the issue's description is adequate source material.
|
||||
- If you don't have source material after a few minutes of searching, comment on the issue with a request for a two- to three-sentence explanation of the change with a link to [guidance about release notes in the content style guide](https://github.com/github/docs/blob/main/contributing/content-style-guide.md#release-notes).
|
||||
|
||||
1. Update the item's "GHES docs status" field.
|
||||
|
||||
- If the item required docs, set the field's value to "Researching".
|
||||
- If the item didn't require docs, set the field's value to "No docs".
|
||||
|
||||
1. Update the value of the item's "GHES release notes status" field to "Researching".
|
||||
|
||||
- If you couldn't locate a source for the release note, comment on the github/releases issue to request a release note, linking to the [content style guide](https://github.com/github/docs-internal/blob/main/contributing/content-style-guide.md#release-notes) for guidance. Set the field's value to "Researching".
|
||||
- If you located a source for the release note, set the field's value to "Ready for work".
|
||||
|
||||
You may want to return to this view daily to update the "GHES release notes status" field, pending a response in the github/releases issue.
|
||||
|
||||
<br/>
|
||||
<a name="validation">
|
||||
|
||||
### [🔬](#validation) Validate docs needs for each of the release's changes
|
||||
|
||||
Validate the versioning within `github/docs-internal` PRs for the changes shipping with the release.
|
||||
|
||||
For each item in the Release Tracker project's [GHES Docs][ghes-release-tracker-project-board-link] view that requires docs, complete the following tasks. If you're collaborating with another writer to validate the content, divide up the sections, or have one writer start at the top of the view and the other at the bottom, working toward the top.
|
||||
|
||||
1. In your browser, navigate to the github/docs-content issue.
|
||||
|
||||
1. From the issue, navigate to the PR for the issue. Assuming the issue is complete or in progress, the "Fixed by..." or "May be fixed by..." link atop the issue is a fast way to get to the PR.
|
||||
|
||||
- If the PR is merged or in progress, validate the versioning.
|
||||
|
||||
1. In the PR's **Files changed** tab, locate the `data/features/` FBV YAML file.
|
||||
|
||||
1. In the top-right corner of the file, select the `•••` dropdown and click **View file**.
|
||||
|
||||
1. In the top-left corner, select the branch dropdown and click **main**.
|
||||
|
||||
1. Validate that the versioning for GHES is correct.
|
||||
|
||||
- If the PR is active and the versioning is incorrect, leave a comment for the author.
|
||||
- If the PR is merged and the versioning is incorrect, copy the link to the FBV YAML file on `main`.
|
||||
|
||||
1. In the Release Tracker project, update the item's "GHES docs status" field.
|
||||
|
||||
- If the docs are done, set the field's value to "Done".
|
||||
- If the docs are in progress, set the field's value to "Active".
|
||||
- If the PR was merged and the FBV was incorrect, set the field's value to "Needs versioning". Paste the link to the FBV YAML file into the "Docs note" field.
|
||||
- If the PR for the docs is yet to be started, set the field's value to "Ready for work".
|
||||
|
||||
<br/>
|
||||
<a name="versioning">
|
||||
|
||||
### [🔢](#versioning) Correct erroneous versioning
|
||||
|
||||
During [validation](#validation), if you set the "GHES docs status" field for any issues in the Release Tracker project's [GHES Docs][ghes-release-tracker-project-board-link] view to "[Needs versioning][ghes-release-tracker-needs-versioning-query]", create a single PR to correct the versioning.
|
||||
|
||||
- Target `main` to get the changes published as soon as possible, particularly if any items slipped from the previous GHES release.
|
||||
- If a change was supposed to be in a previous release but you needed to update the versioning to reflect that it's in this upcoming release, you may need to relocate the release note for the feature in the prior version into the [Errata](https://github.com/github/docs-internal/blob/main/contributing/content-style-guide.md#errata) section and include the release note in the upcoming release.
|
||||
|
||||
After you merge the PR, update the status for each item in the Release Tracker project's [GHES Docs][ghes-release-tracker-project-board-link] view with a "GHES docs status" field set to [Needs versioning][ghes-release-tracker-needs-versioning-query].
|
||||
|
||||
<br/>
|
||||
<a name="release-note-preparation">
|
||||
|
||||
### [🆕](#release-note-preparation) Gather and edit release notes
|
||||
|
||||
Create a PR containing the RC's release notes.
|
||||
|
||||
1. From the topic branch that you created for the PR to close {{ release-steps-1-url }}, create a new branch named `ghes-VERSION-rc/add-release-notes`. For example, `ghes-3.10-rc/add-release-notes`.
|
||||
|
||||
1. Update `data/release-notes/enterprise-server/VERSION/PLACEHOLDER.yml`, where VERSION is the RC's version number with the major and minor versions separated by a hyphen.
|
||||
|
||||
1. Rename the file to `0-rc1.yml`.
|
||||
|
||||
1. Edit the value of `date` on the first line to reflect the RC's release date.
|
||||
|
||||
1. Add, commit, and push the changes.
|
||||
|
||||
1. For each item in the Release Tracker project's [GHES Docs][ghes-release-tracker-project-board-link] view with a "GHES release notes status" field set to "[Ready for work][ghes-release-tracker-ready-for-work]", review the link in the "Release notes source" field.
|
||||
|
||||
1. In your text editor of choice, edit the release note. If you would like technical review, contact the owner of the corresponding issue in `github/releases`. For more information about how we write release notes, see [Release notes](https://github.com/github/docs-internal/blob/main/contributing/content-style-guide.md#release-notes) in the GitHub Docs content style guide.
|
||||
|
||||
1. Determine which section to place the note in, and add the edited release note to the section.
|
||||
|
||||
- For brand-new functionality or deprecations, review the value for the item's "Customer Theme" field. (Deprecations are their own "Customer Theme".)
|
||||
- Categorize any other changes to the product's behavior in the "Changes" section.
|
||||
|
||||
1. Add, commit, and push the changes.
|
||||
|
||||
1. Set the value for the item's "GHES release notes status" field to "In PR".
|
||||
|
||||
1. Prepare release notes for the release's known issues.
|
||||
|
||||
1. Ensure that the GHES Releases PM has triaged existing known issues for the release. Per the [process for known issues](https://thehub.github.com/epd/engineering/products-and-services/ghes/releases/known-issues/), each issue should have a `enterprise-#.#-known-issue` label that reflects the releases with the known issue.
|
||||
|
||||
1. Filter the view with the [existing known issues](https://github.com/orgs/github/projects/7908/views/15) by the `enterprise-#.#-known-issue` label for the release you're drafting release notes for.
|
||||
|
||||
1. For each issue in the filtered view, copy the value of the "Body" field. In `0-rc1.yml`, paste the value as a new entry within the `known_issues` section. Add, commit, and push the change.
|
||||
|
||||
1. After you've added all of the release notes, delete any unused sections within `0-rc1.yml`.
|
||||
|
||||
<br/>
|
||||
<a name="release-note-finalization">
|
||||
|
||||
### [💅](#release-note-finalization) Finalize and share release notes
|
||||
|
||||
At least a week before the ship date for the RC, request review of the PR with the release notes, then incorporate changes.
|
||||
|
||||
1. Request review of the PR with the release notes.
|
||||
|
||||
- Request writer review.
|
||||
- Request review from the GHES Releases PM.
|
||||
|
||||
1. Incorporate any changes.
|
||||
|
||||
1. After you've received writer and PM approval, merge the PR into the topic branch that you created for the PR to close {{ release-steps-1-url }}.
|
||||
|
||||
1. Link the PR to this issue as well. 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).
|
||||
|
||||
1. To provide other GTM teams like Support Delivery an advance look at changes in the release, share a link to the release notes on the staging deployment and a link to the YAML file in **Files changed** tab within the PR for {{ release-steps-1-url }}.
|
||||
|
||||
- Request that readers provide any feedback in the PR's **Files changed** tab.
|
||||
- Share the links in [GHES release issue][ghes-release-issue].
|
||||
- Share the links in [GHES release slack channel](ghes-release-slack-channel-link) on Slack.
|
||||
|
||||
<br/>
|
||||
<a name="publication">
|
||||
|
||||
### [🚢](#publication) Complete preparation for the RC and publish the docset
|
||||
|
||||
To complete preparation and publish the docset, continue the tasks in {{ release-steps-0-url }}. Leave this issue open until you merge the publication PR.
|
||||
* [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
|
||||
* [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
|
||||
|
||||
## Swarming release notes
|
||||
|
||||
If you can contribute to the {{ release-number }} release notes, edit the table below assign yourself a section of the [GHES Docs](https://github.com/orgs/github/projects/2463/views/76) view, then follow these instructions for that section:
|
||||
|
||||
* [🔬 Validate docs needs for each of the release's changes](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#22--validate-docs-needs-for-each-of-the-releases-changes)
|
||||
* [🔢 Correct erroneous versioning](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#23--correct-erroneous-versioning)
|
||||
* [🆕 Gather and edit release notes](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#24--gather-and-edit-release-notes) (but just add your release note drafts as a comment in this issue, [like this](https://github.com/github/docs-content/issues/16980#issuecomment-2643024573))
|
||||
|
||||
| Board section | Assignee |
|
||||
| ------------- | -------- |
|
||||
| Actions and Workflows | @ |
|
||||
| APIs | @ |
|
||||
| DevEx | @ |
|
||||
| Admin Experience | @ |
|
||||
| Deprecations | @ |
|
||||
| DevEx - Productivity | @ |
|
||||
| Enterprise importer (GEI) | @ |
|
||||
| GHES Core Updates | @ |
|
||||
| Mobile | @ |
|
||||
| Security - Advanced Security* | @ |
|
||||
| Security - General Security | @ |
|
||||
| Community Experience | @ |
|
||||
| No Customer Theme | @ |
|
||||
|
||||
# Tasks
|
||||
|
||||
To [prepare for a GHES RC](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#2-prepare-content-for-release-candidate), you will:
|
||||
* [ ] [🔍 Populate the Release Tracker's "GHES Docs" view](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#21--populate-the-release-trackers-ghes-docs-view)
|
||||
* [ ] [🔬 Validate docs needs for each of the release's changes](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#22--validate-docs-needs-for-each-of-the-releases-changes)
|
||||
* [ ] [🔢 Correct erroneous versioning](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#23--correct-erroneous-versioning)
|
||||
* [ ] [🆕 Gather and edit release notes](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#24--gather-and-edit-release-notes)
|
||||
* [ ] [💅 Finalize and share release notes](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#25--finalize-and-share-release-notes)
|
||||
* [ ] 🚢 Continue the tasks in {{ release-steps-0-url }} to complete preparation and publish the docset. Leave this issue open until you merge the publication PR.
|
||||
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -8,26 +8,22 @@ labels:
|
||||
- workflow-generated
|
||||
---
|
||||
|
||||
Docs Content will publish docs for the GHES {{ release-number }} RC soon. Please draft a release note for the latest supported version of the CodeQL CLI, and update the docs to reflect the latest supported version.
|
||||
Docs Content will publish docs for the GHES {{ release-number }} RC soon, and we need to update the [CodeQL CLI latest supported version](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#codeql-cli).
|
||||
|
||||
```[tasklist]
|
||||
### Draft a release note
|
||||
- [ ] Draft a consolidated release note that summarizes the most important updates to the CodeQL CLI since the supported version for the previous GHES release. See the [docs style guide section for release notes](https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#features).
|
||||
- [ ] Add the draft as a comment in this issue, and ping the `@github/docs-content-enterprise` team for review.
|
||||
```
|
||||
### The CodeQL team will draft a release note
|
||||
* [ ] Draft a consolidated release note that summarizes the most important updates to the CodeQL CLI since the supported version for the previous GHES release. See the [docs style guide section for release notes](https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#features).
|
||||
* [ ] Add the draft as a comment in this issue, and ping the `@github/docs-content-enterprise` team for review.
|
||||
|
||||
```[tasklist]
|
||||
### Update the docs
|
||||
- [ ] In a PR in github/docs-internal, add the latest supported CodeQL CLI version to the `codeql_cli_ghes_recommended_version` variable in [`product.yml`](https://github.com/github/docs-internal/blob/main/data/variables/product.yml)
|
||||
- [ ] In the same PR, add the latest supported CodeQL CLI version to the [table in the "GitHub Enterprise Server releases" article](https://github.com/github/docs-internal/blob/main/content/admin/all-releases.md?plain=1#L53).
|
||||
```
|
||||
### The Docs team will update the docs
|
||||
* [ ] In a PR in github/docs-internal, add the latest supported CodeQL CLI version to the `codeql_cli_ghes_recommended_version` variable in [`product.yml`](https://github.com/github/docs-internal/blob/main/data/variables/product.yml)
|
||||
* [ ] In the same PR, add the latest supported CodeQL CLI version to the [table in the "GitHub Enterprise Server releases" article](https://github.com/github/docs-internal/blob/main/content/admin/all-releases.md?plain=1#L53).
|
||||
|
||||
| Field | Value |
|
||||
| ----- | ----- |
|
||||
| Target date | {{ release-target-date }} |
|
||||
| Release issue | [link][release-issue] |
|
||||
|
||||
**Note**: We publish docs for each GHES release when the RC ships. The target date reflects a few days prior to the GHES 3.13 RC's release date, while the release issue reflects the GA's release date.
|
||||
**Note**: We publish docs for each GHES release when the RC ships. The target date reflects a few days prior to the GHES {{ release-number }} RC's release date, while the release issue reflects the GA's release date.
|
||||
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -7,30 +7,20 @@ labels:
|
||||
- workflow-generated
|
||||
---
|
||||
|
||||
Docs Content will publish docs for the GHES {{ release-number }} RC soon. Please update the docs to reflect the minimum required version of the Actions Runner application for the new release.
|
||||
Docs Content will publish docs for the GHES {{ release-number }} RC soon. Please update the docs to reflect the [minimum required version of the Actions Runner application](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#actions-runner) for the new release.
|
||||
|
||||
| Field | Value |
|
||||
| ----- | ----- |
|
||||
| Target date | {{ release-target-date }} |
|
||||
| Release issue | [link][release-issue] |
|
||||
|
||||
**Note**: We publish docs for each GHES release when the RC ships. The target date reflects a few days prior to the GHES 3.13 RC's release date, while the release issue reflects the GA's release date.
|
||||
**Note**: We publish docs for each GHES release when the RC ships. The target date reflects a few days prior to the GHES {{ release-number }} RC's release date, while the release issue reflects the GA's release date.
|
||||
|
||||
```[tasklist]
|
||||
### Tasks
|
||||
- [ ] Find the minimum required Actions Runner version for the upcoming GHES release (see below for help).
|
||||
- [ ] Create a PR against the release candidate publication branch in github/docs-internal to add the version to the [table in the "GitHub Enterprise Server releases" article](https://github.com/github/docs-internal/blob/main/content/admin/all-releases.md?plain=1#L66).
|
||||
- [ ] In the same PR, add the version to the [`runner_required_version` variable](https://github.com/github/docs-internal/blob/main/data/variables/product.yml#L140) in product.yml.
|
||||
- [ ] Once the release notes file for the release has been generated (see https://github.com/github/docs-content/issues/14225), confirm that the {% raw %}`{% data reusables.actions.actions-runner-release-note %}`{% endraw %} reusable is present in the release notes.
|
||||
```
|
||||
|
||||
### Finding the required Actions Runner version for a release
|
||||
|
||||
To find the required version of the Runner app for a GHES release, navigate to `https://github.com/github/ghes-actions/blob/enterprise-X.Y-release/config/runners/runners.json`, replacing `X.Y` with a release number such as `{{ release-number }}`.
|
||||
|
||||
You can find the minimum required version for the release in the `version` field of any object in the array.
|
||||
|
||||
The `runners.json` file is generally available with plenty of time before a release. If you can't find a file at that location, ask in the `#actions` channel on Slack.
|
||||
# Tasks
|
||||
* [ ] Find the minimum required Actions Runner version for the upcoming GHES release (see below for help).
|
||||
* [ ] Create a PR against the release candidate publication branch in github/docs-internal to add the version to the [table in the "GitHub Enterprise Server releases" article](https://github.com/github/docs-internal/blob/main/content/admin/all-releases.md?plain=1#L66).
|
||||
* [ ] In the same PR, add the version to the [`runner_required_version` variable](https://github.com/github/docs-internal/blob/main/data/variables/product.yml#L140) in product.yml.
|
||||
* [ ] Once the release notes file for the release has been generated, confirm that the {% raw %}`{% data reusables.actions.actions-runner-release-note %}`{% endraw %} reusable is present in the release notes.
|
||||
|
||||
<!--
|
||||
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.
|
||||
|
||||
@@ -12,162 +12,14 @@ labels:
|
||||
|
||||
## Instructions for triage
|
||||
|
||||
- [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
|
||||
- [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
|
||||
* [ ] Add this issue to the [Rhythm of Docs: Operations](https://github.com/orgs/github/projects/20190) project.
|
||||
* [ ] For assignee: if needed, add this issue to your persona team project for tracking purposes.
|
||||
|
||||
## Instructions for assignee
|
||||
## Tasks
|
||||
|
||||
To incorporate updates to our REST API and webhook documentation into the publication branch you created for {{ release-steps-1-url }}, you must prepare a release configuration in `github/github`, prepare the new assets for publication, coordinate the generation of the new OpenAPI content, then merge the content into your publication branch.
|
||||
To incorporate updates to our REST API and webhook documentation into the publication branch you created for {{ release-steps-1-url }}, you must prepare a release configuration in `github/github`, prepare the new assets for publication, coordinate the generation of the new OpenAPI content, then merge the content into your publication branch as described in [Prepare OpenAPI assets for release candidate](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#5-prepare-openapi-assets-for-release-candidate).
|
||||
|
||||
- [Prepare OpenAPI release configuration](#release-configuration-preparation)
|
||||
- [Prepare PR to publish release](#publication-preparation)
|
||||
- [Merge OpenAPI changes into publication branch](#merge) 🗓️ **Thursday before release**
|
||||
- [Complete preparation for the RC and publish the docset](#publication)
|
||||
|
||||
<br/>
|
||||
<a name="release-configuration-preparation">
|
||||
|
||||
### [🚀](#release-configuration-preparation) Prepare OpenAPI release configuration
|
||||
|
||||
For each GHES release, there's a corresponding OpenAPI configuration. Ensure it's present. The [API team](https://github.com/github/ecosystem-api) often completes these steps before we prepare for a GHES RC, so some of this work may already be complete.
|
||||
|
||||
- [ ] In `github/github`, within [`app/api/description/config/releases`](https://github.com/github/github/tree/master/app/api/description/config/releases), check for a `ghes-VERSION.yaml` file, where VERSION is the version we're releasing. (**Note**: These steps were already done when I created this tracking issue.)
|
||||
|
||||
- **If the file exists**, validate its contents.
|
||||
|
||||
- [ ] `published` should be set to `false`.
|
||||
|
||||
- [ ] Any references to a GHES version should reflect the version we're releasing.
|
||||
|
||||
- [ ] Beneath `path: "/info/x-github-api-versions"`, the `value` should be the API's calendar date version for the prior release of GHES from [`release_api_versioning_support.yaml`](https://github.com/github/github/blob/master/app/api/description/config/release_api_versioning_support.yaml).
|
||||
|
||||
- **If the file doesn't exist**, prepare a PR.
|
||||
|
||||
- [ ] Within a codespace in `github/github`, from `master`, create a new branch named `ghes-VERSION-rc/add-release-configuration`. For example, `ghes-3.10-rc/add-release-configuration`.
|
||||
|
||||
- [ ] To copy an existing release configuration into place, run the following command, replacing LATEST-VERSION with the last version we released, and VERSION-TO-RELEASE with the version we're releasing.
|
||||
|
||||
```shell
|
||||
cp app/api/description/config/releases/ghes-LATEST-VERSION.yaml app/api/description/config/releases/ghes-VERSION-TO-RELEASE.yaml
|
||||
```
|
||||
|
||||
- [ ] Edit the `app/api/description/config/releases/ghes-VERSION-TO-RELEASE.yaml` file that you created.
|
||||
|
||||
- [ ] Set `published` to `false`.
|
||||
|
||||
- [ ] Find and replace any occurrences of the prior version with the version that we're releasing. At the time of writing, the following four keys include values that reference the version number.
|
||||
|
||||
- `variables.externalDocsUrl`
|
||||
|
||||
- `variables.ghesVersion`
|
||||
|
||||
- Two keys under `patch` for the paths `/info/x-github-release` and `/externalDocs`
|
||||
|
||||
- [ ] Edit [`app/api/description/config/release_api_versioning_support.yaml`](https://github.com/github/github/blob/master/app/api/description/config/release_api_versioning_support.yaml).
|
||||
|
||||
- [ ] Copy the line for the previous release of GHES and the API's calendar-date version on the row beneath it.
|
||||
|
||||
- [ ] Paste the line beneath the previous version and its API version, and edit the line to reflect the version we're releasing.
|
||||
|
||||
- [ ] Create a PR targeting `master` with the changes in your topic branch.
|
||||
|
||||
- [ ] Get the necessary reviews, then deploy and merge the PR.
|
||||
|
||||
<br/>
|
||||
<a name="publication-preparation">
|
||||
|
||||
### [🆕](#publication-preparation) Prepare PR to publish release
|
||||
|
||||
To prepare for publication, create a PR in `github/github` that publishes the schema for the release.
|
||||
|
||||
- [ ] In `github/github`, edit `app/api/description/config/releases/ghes-VERSION-TO-RELEASE.yaml`, where VERSION-TO-RELEASE is the version we're releasing.
|
||||
|
||||
- [ ] Set `published` to `true`.
|
||||
|
||||
- [ ] Create a PR.
|
||||
|
||||
- [ ] Get the necessary reviews, but **do not deploy and merge the PR yet**. You'll merge this PR closer to the RC's release date.
|
||||
|
||||
<br/>
|
||||
<a name="merge">
|
||||
|
||||
### [👯](#merge) Integrate OpenAPI changes into publication branch
|
||||
|
||||
To trigger creation of an OpenAPI PR with the updated schema for the RC, merge your publication PR in `github/github`.
|
||||
|
||||
- [ ] 2-3 days before the RC release date, merge the publication PR you [prepared in `github/github`](#publication-preparation).
|
||||
|
||||
- [ ] In [#api-platform](https://github.slack.com/archives/C1042T6MS) on Slack, update and then post the following message to notify the team of the upcoming release. Replace VERSION with the version we're releasing.
|
||||
|
||||
> 👋 Hi from Docs! We have just marked `published` for the GHES VERSION release configuration to `true`. Please **do not** merge subsequent "Update OpenAPI 3.x Descriptions" PRs [in github/rest-api-description](https://github.com/github/rest-api-description/pulls) until further notice. Thanks!
|
||||
|
||||
- [ ] Locate the latest "Update OpenAPI 3.x Descriptions" PRs [in `github/rest-api-description`](https://github.com/github/rest-api-description/pulls).
|
||||
|
||||
- [ ] On each new PR, leave a review that requests changes with the following comment.
|
||||
|
||||
> This PR contains changes for the upcoming GHES RC. Please do not merge this or subsequent PRs until further notice in #ecosystem-api. Thanks!
|
||||
|
||||
- [ ] From now until the RC ships, all [existing "Update OpenAPI Description" PRs](https://github.com/github/docs-internal/labels/github-openapi-bot) in `github/docs-internal` can be closed.
|
||||
|
||||
To get the latest changes from the latest "Update OpenAPI 3.x Descriptions" PR in the `github/rest-api-description` repository into your PR to close {{ release-steps-1-url }}, you can use one of two methods.
|
||||
|
||||
The benefit of the first method is that you don't need to deal with merging two PRs together, you can just make a new commit directly to the GHES release branch with the updated OpenAPI data. If you aren't as comfortable in the terminal, the second method is best.
|
||||
|
||||
#### Method 1: Generation of new data locally
|
||||
|
||||
- [ ] In a local clone of the `github/docs-internal` repository, clone `github/rest-api-description`.
|
||||
- [ ] Ensure that your local clone of `github/docs-internal` contains a `rest-api-description` directory with the contents of the `github/rest-api-description` repository.
|
||||
- [ ] In the [list of PRs for `github/rest-api-description`](https://github.com/github/rest-api-description/pulls), find the latest "Update OpenAPI 3.1 Descriptions" PR. Note the name of the PR's topic branch.
|
||||
- [ ] In your local clone of `github/docs-internal`, move into the `rest-api-description` directory, then check out the branch from the previous step. Replace NAME-OF-REST-API-DESCRIPTION-BRANCH with the name of the branch.
|
||||
|
||||
```shell
|
||||
cd rest-api-description
|
||||
git checkout NAME-OF-REST-API-DESCRIPTION-BRANCH
|
||||
```
|
||||
|
||||
- [ ] Move back into the directory with your clone of `github/docs-internal`.
|
||||
- [ ] Check out the topic branch for the GHES RC. For example, if the branch is `ghes-3.13-rc`, replace NAME-OF-PUBLICATION-BRANCH with ghes-3.13-rc.
|
||||
|
||||
```shell
|
||||
git checkout NAME-OF-PUBLICATION-BRANCH
|
||||
```
|
||||
|
||||
- [ ] To ensure the checks pass with the incoming OpenAPI data in isolation from the publication branch, create a new branch. Replace NAME-OF-BRANCH with a name that reflects the change. For example, if you're preparing for GHES 3.13, replace NAME-OF-BRANCH with ghes-3.13-openapi.
|
||||
- [ ] To update the OpenAPI data, run the following command.
|
||||
|
||||
```shell
|
||||
npm run sync-rest -- --source-repo rest-api-description --output rest github-apps webhooks rest-redirects
|
||||
```
|
||||
|
||||
You may see an error that indicates that "...you must have the GITHUB_TOKEN environment variable set to access the programmatic access and resource files via the GitHub REST API." You can ignore this error.
|
||||
- [ ] Add and commit the modified files.
|
||||
|
||||
```shell
|
||||
git add .
|
||||
git commit -m "Add generated OpenAPI files"
|
||||
```
|
||||
|
||||
- [ ] Push your changes.
|
||||
- [ ] To run the tests and check the data, create a PR for the new branch. During creation of the PR, set the base branch to the publication branch for the RC.
|
||||
- [ ] Wait for the checks to run in the new PR.
|
||||
- [ ] After the checks pass, merge the PR. If you need assistance, request support from Docs Engineering.
|
||||
|
||||
#### Method 2: Generate automated OpenAPI PR in `github/docs-internal`
|
||||
|
||||
- [ ] In the `github/docs-internal` repository, navigate to the [Sync OpenAPI schema](https://github.com/github/docs-internal/actions/workflows/sync-openapi.yml) workflow.
|
||||
- [ ] To run the workflow, click "Run workflow".
|
||||
- [ ] Under "Use workflow from," select the branch that contains the new GHES release. This will base the new PR on the GHES release branch and will generate the OpenAPI data for the new GHES release.
|
||||
- [ ] Under **Branch to pull the dereferenced OpenAPI source files from in the github/rest-api-descriptions repo**, select the branch name of the data you want to consume in `github/rest-api-description`. If the branch in `github/rest-api-description` is not yet merged, select the branch name of the PR in `github/rest-api-description` that contains the new GHES release schema. If the PR that was opened in `github/rest-api-description` was merged to main, leave the second option set to `main`.
|
||||
- [ ] Click the green "Run workflow" button.
|
||||
- [ ] Wait for the workflow to finish. It will automatically open a new ["Update OpenAPI Description" PR](https://github.com/github/docs-internal/labels/github-openapi-bot). The workflow output log will include a PR number.
|
||||
- [ ] In the new PR with OpenAPI changes, change the base branch of the PR from `main` to the branch of the to the publication branch you created for https://github.com/github/docs-content/issues/14225.
|
||||
- [ ] Link the PR to this issue. For more information, 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).
|
||||
- [ ] In the "Update OpenAPI Description" PR, ensure that there are no merge conflicts and that checks pass, paying particular attention to links that were broken due to missing OpenAPI-related content.
|
||||
- [ ] Merge "Update OpenAPI Description" PR into your publication PR.. **Note:** Don't attempt to resolve conflicts for changes to the `src/rest/data` files. Only accept the incoming files. If you do see conflicts in the `src/rest/data`, `src/webhooks/data`, or `src/github-apps/data` directories, you can checkout the files for those directories that exist in the main branch, which reverts the changes in those directories to the files in the `main` branch (e.g. `git checkout origin/main src/rest/data/*`).
|
||||
|
||||
<br/>
|
||||
<a name="publication">
|
||||
|
||||
### [🚢](#publication) Complete preparation for the RC and publish the docset
|
||||
|
||||
To complete preparation and publish the docset, continue the tasks in {{ release-steps-0-url }}. Leave this issue open until you merge the publication PR.
|
||||
* [ ] [🚀 Prepare OpenAPI release configuration](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#51--prepare-openapi-release-configuration)
|
||||
* [ ] [🆕 Prepare PR to publish release](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#52--prepare-pr-to-publish-release)
|
||||
* [ ] [👯 Integrate OpenAPI changes into publication branch](https://github.com/github/docs-content/blob/main/focus-areas/enterprise/processes/publishing-ghes-feature-release-docs.md#53--integrate-openapi-changes-into-publication-branch) 🗓️ **2-3 days before release**
|
||||
* [ ] Continue the tasks in {{ release-steps-0-url }} to complete preparation and publish the docset. Leave this issue open until you merge the publication PR.
|
||||
|
||||
Reference in New Issue
Block a user