remove openapi dereferenced static files (#33297)
This commit is contained in:
Rachael Sewell
@@ -18,7 +18,7 @@ If you aren't comfortable going through the steps alone, sync up with a docs eng
|
||||
```
|
||||
script/update-enterprise-dates.js
|
||||
```
|
||||
- [ ] Create REST files based on previous version. Copy the latest GHES version of the dereferenced file from `lib/rest/static/dereferenced` to a new file in the same directory for the new GHES release. Ex, `cp lib/rest/static/dereferenced/ghes-3.4.deref.json lib/rest/static/dereferenced/ghes-3.5.deref.json`. Then run `script/rest/update-files.js --decorate-only` and check in the resulting files.
|
||||
- [ ] Create REST files based on previous version. Copy the latest GHES version of the decorate file from `lib/rest/static/decorated` to a new file in the same directory for the new GHES release. Ex, `cp lib/rest/static/decorated/ghes-3.4.json lib/rest/static/decorated/ghes-3.5.json`.
|
||||
|
||||
- [ ] Create GraphQL files based on previous version:
|
||||
|
||||
@@ -76,16 +76,6 @@ If you aren't comfortable going through the steps alone, sync up with a docs eng
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
#### `OpenAPI dev mode check / check-schema-versions` failures
|
||||
|
||||
If the `OpenAPI dev mode check / check-schema-versions` check fails with the following message:
|
||||
|
||||
> :construction::warning: Your decorated and dereferenced schema files don't match. Ensure you're using decorated and dereferenced schemas from the automatically created pull requests by the 'github-openapi-bot' user. For more information, see 'script/rest/README.md'
|
||||
|
||||
- run `git checkout origin/main lib/rest/static/*`
|
||||
- run `script/enterprise-server-releases/create-rest-files.js --oldVersion enterprise-server@<LATEST PUBLIC RELEASE NUMBER> --newVersion enterprise-server@<NEW RELEASE NUMBER>`
|
||||
- push the resulting changes
|
||||
|
||||
#### `Node.js tests / test content` failures
|
||||
|
||||
If the `Node.js tests / test content` check fails with the following message, the `lib/enterprise-dates.json` file is not up-to-date:
|
||||
@@ -104,7 +94,7 @@ This file should be automatically updated, but you can also run `script/update-e
|
||||
- [ ] [Freeze the repos](https://github.com/github/docs-content/blob/main/docs-content-docs/docs-content-workflows/freezing.md) at least 1-2 days before the release, and post an announcement in Slack so everybody knows. It's helpful to freeze the repos before doing the OpenAPI merges to avoid changes to the megabranch while preparing and deploying.
|
||||
- [ ] Alert the Neon Squad (formally docs-ecosystem team) 1-2 days before the release to deploy to `github/github`. A PR should already be open in `github/github`, to change the OpenAPI schema config `published` to `true` in `app/api/description/config/releases/ghes-<NEXT RELEASE NUMBER>.yaml`. They will need to:
|
||||
- [ ] Get the required approval from `@github/ecosystem-api-reviewers` then deploy the PR to dotcom. This process generally takes 30-90 minutes.
|
||||
- [ ] Once the PR merges, make sure that the auto-generated PR titled "Update OpenAPI Descriptions" in doc-internal contains both the dereferenced and decorated JSON files for the new GHES release. If everything looks good, merge the "Update OpenAPI Description" PR into the GHES release megabranch. **Note:** Be careful about resolving the conflicts correctly—you may wish to delete the existing OpenAPI files for the release version from the megabranch (that is, delete the GHES release version `lib/rest/static` decorated and dereferenced JSON files), so there are no conflicts to resolve and to ensure that the incoming artifacts are the correct ones.
|
||||
- [ ] Once the PR merges, make sure that the auto-generated PR titled "Update OpenAPI Descriptions" in doc-internal contains the decorated JSON files for the new GHES release. If everything looks good, merge the "Update OpenAPI Description" PR into the GHES release megabranch. **Note:** Don't attempt to resolve conflicts for changes to the `lib/rest/static/decorated` files. Instead delete the existing OpenAPI files for the release version from the megabranch (that is, revert the changes to the `lib/rest/static` decorated JSON files, e.g., from the megabranch do a `git checkout origin/main lib/rest/static/*`), so there are no conflicts to resolve and to ensure that the incoming artifacts are the correct ones.
|
||||
- [ ] Alert the Ecosystem-API team in #ecosystem-api about the pending release freeze and incoming blocking review of OpenAPI updates in the public REST API description (the `rest-api-descriptions` repo). They'll need to block any future "Update OpenAPI Descriptions" PRs in the public REST API description until after the ship.
|
||||
- [ ] Add a blocking review to the auto-generated "Update OpenAPI Descriptions" PR in the public REST API description. (You or they will remove this blocking review once the GHES release ships.)
|
||||
|
||||
|
||||
46
.github/actions-scripts/openapi-schema-branch.js
vendored
46
.github/actions-scripts/openapi-schema-branch.js
vendored
@@ -1,46 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import fs from 'fs'
|
||||
import path from 'path'
|
||||
import { execSync } from 'child_process'
|
||||
import semver from 'semver'
|
||||
|
||||
/*
|
||||
* This script performs two checks to prevent shipping development mode OpenAPI schemas:
|
||||
* - Ensures the `info.version` property is a semantic version.
|
||||
* In development mode, the `info.version` property is a string
|
||||
* containing the `github/github` branch name.
|
||||
* - Ensures the decorated schema matches the dereferenced schema.
|
||||
* The workflow that calls this script runs `script/rest/update-files.js`
|
||||
* with the `--decorate-only` switch then checks to see if files changed.
|
||||
*
|
||||
*/
|
||||
|
||||
// Check that the `info.version` property is a semantic version
|
||||
const dereferencedDir = path.join(process.cwd(), 'lib/rest/static/dereferenced')
|
||||
const schemas = fs.readdirSync(dereferencedDir)
|
||||
|
||||
schemas.forEach((filename) => {
|
||||
const schema = JSON.parse(fs.readFileSync(path.join(dereferencedDir, filename)))
|
||||
if (!semver.valid(schema.info.version)) {
|
||||
console.log(
|
||||
`🚧⚠️ Your branch contains a development mode OpenAPI schema: ${schema.info.version}. This check is a reminder to not 🚢 OpenAPI files in development mode. 🛑`
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
})
|
||||
|
||||
// Check that the decorated schema matches the dereferenced schema
|
||||
const changedFiles = execSync('git diff --name-only HEAD').toString()
|
||||
|
||||
if (changedFiles !== '') {
|
||||
console.log(`These files were changed:\n${changedFiles}`)
|
||||
console.log(
|
||||
`🚧⚠️ Your decorated and dereferenced schema files don't match. Ensure you're using decorated and dereferenced schemas from the automatically created pull requests by the 'github-openapi-bot' user. \n\n If this test is failing after updates to the script/rest directory, run script/rest/update-files.js --decorate-only to re-generate the decorated files from the existing dereferenced files and check those in. \n\n If this test is failing after an update to a package, check the changes the new package makes to the decorated files by running script/rest/update-files.js --decorate-only.\n\nIf you updated script/rest/utils/rest-api-overrides.json, you'll need to run script/rest/update-files.js --decorate-only to regenerate the decorated file and redirects file (check in the changed lib/rest/static/decorated files).\n\nIf the changes are small style changes that don't impact the overall experience, check the updated decorated file in. Otherwise, more work may be needed to be compatible with the updated package. \n\n For more information, see 'script/rest/README.md'. 🛑`
|
||||
)
|
||||
process.exit(1)
|
||||
}
|
||||
|
||||
// All checks pass, ready to ship
|
||||
console.log('All good 👍')
|
||||
process.exit(0)
|
||||
13
.github/workflows/openapi-decorate.yml
vendored
13
.github/workflows/openapi-decorate.yml
vendored
@@ -65,3 +65,16 @@ jobs:
|
||||
env:
|
||||
# Disable pre-commit hooks; they don't play nicely with add-and-commit
|
||||
HUSKY: '0'
|
||||
|
||||
- name: Remove the dereferenced files
|
||||
uses: EndBug/add-and-commit@050a66787244b10a4874a2a5f682130263edc192
|
||||
with:
|
||||
# The arguments for the `git add` command
|
||||
remove: '["lib/rest/static/dereferenced/*"]'
|
||||
|
||||
# The message for the commit
|
||||
message: 'Removed dereferenced OpenAPI schema files'
|
||||
|
||||
env:
|
||||
# Disable pre-commit hooks; they don't play nicely with add-and-commit
|
||||
HUSKY: '0'
|
||||
|
||||
59
.github/workflows/openapi-schema-check.yml
vendored
59
.github/workflows/openapi-schema-check.yml
vendored
@@ -1,59 +0,0 @@
|
||||
name: OpenAPI dev mode check
|
||||
|
||||
# **What it does**: Checks that the files in lib/rest/static/decorated match
|
||||
# the files in lib/rest/static/dereferenced. Checks that the decorated
|
||||
# schemas in lib/rest/static/decorated are not in development mode.
|
||||
# Development mode schemas have a branch name and development mode tag in the
|
||||
# info.version property.
|
||||
# **Why we have it**: To ensure that we aren't every shipping decorated schemas
|
||||
# that are out of sync with the source derefereced schema. To ensure that
|
||||
# decorated schemas generated locally are not published. Locally generated
|
||||
# decorated schemas are pushing up to the remote for staging purposes only.
|
||||
# **Who does it impact**: Docs content writers updating REST API docs and
|
||||
# the docs engineering team as maintainers of the scripts and workflows.
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request:
|
||||
paths:
|
||||
- 'lib/rest/static/**'
|
||||
- 'script/rest/**/*.js'
|
||||
- 'script/rest/**/*.json'
|
||||
- 'package*.json'
|
||||
- 'lib/redirects/static/**/*.json'
|
||||
- '.github/workflows/openapi-schema-check.yml'
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
# This allows a subsequently queued workflow run to interrupt previous runs
|
||||
concurrency:
|
||||
group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
check-schema-versions:
|
||||
if: ${{ github.repository == 'github/docs-internal' }}
|
||||
runs-on: ubuntu-20.04-xl
|
||||
steps:
|
||||
- name: Checkout repository code
|
||||
uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8
|
||||
|
||||
- name: Setup node
|
||||
uses: actions/setup-node@8c91899e586c5b171469028077307d293428b516
|
||||
with:
|
||||
node-version: '16.17.0'
|
||||
cache: npm
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
# Differences between decorated and dereferenced files indicates a problem
|
||||
- name: Generate decorated files to check that there are no differences
|
||||
run: script/rest/update-files.js --decorate-only
|
||||
|
||||
- name: Check if deref/decorated schemas are dev mode and that they match
|
||||
run: .github/actions-scripts/openapi-schema-branch.js
|
||||
Reference in New Issue
Block a user