diff --git a/.github/actions-scripts/enterprise-server-issue-templates/deprecation-issue.md b/.github/actions-scripts/enterprise-server-issue-templates/deprecation-issue.md index d1c171b849..c7b4dca6f1 100644 --- a/.github/actions-scripts/enterprise-server-issue-templates/deprecation-issue.md +++ b/.github/actions-scripts/enterprise-server-issue-templates/deprecation-issue.md @@ -121,7 +121,7 @@ Poke around several pages, ensure that the stylesheets are working properly, ima - [ ] In your `docs-internal` checkout, create a new branch `remove--static-files` branch: `git checkout -b remove--static-files` (you can branch off of `main` or from your `deprecate-` branch, up to you). - [ ] Run `script/enterprise-server-deprecations/remove-static-files.js` and commit results. -- [ ] Re-generate the static files by running `script/rest/update-files.js --decorate-only`. +- [ ] Re-generate the static files by running `src/rest/scripts/update-files.js --decorate-only`. - [ ] Open a new PR. - [ ] Get a review from docs-engineering and merge. This step can be merged independently from step 6. The purpose of splitting up steps 5 and 6 is to focus the review on specific files. diff --git a/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md b/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md index eb53adb7fd..2f6eed5569 100644 --- a/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md +++ b/.github/actions-scripts/enterprise-server-issue-templates/release-issue.md @@ -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 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 REST files based on previous version. Copy the latest GHES version of the decorate file from `src/rest/data` to a new file in the same directory for the new GHES release. Ex, `cp src/rest/data/ghes-3.4.json src/rest/data/ghes-3.5.json`. - [ ] Create GraphQL files based on previous version: @@ -94,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-.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 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. + - [ ] 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 `src/rest/data` files. Instead delete the existing OpenAPI files for the release version from the megabranch (that is, revert the changes to the `src/rest/data` decorated JSON files, e.g., from the megabranch do a `git checkout origin/main src/rest/data/*`), 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.) diff --git a/.github/workflows/openapi-decorate.yml b/.github/workflows/openapi-decorate.yml index d4f55043e6..e2459bae63 100644 --- a/.github/workflows/openapi-decorate.yml +++ b/.github/workflows/openapi-decorate.yml @@ -52,8 +52,8 @@ jobs: - name: Copy dereferenced OpenAPI files id: rest-api-description run: | - mkdir ./lib/rest/static/dereferenced - find rest-api-description/descriptions-next -type f -name "*.deref.json" -exec sh -c 'cp $1 ./lib/rest/static/dereferenced' sh {} \; + mkdir ./src/rest/data/dereferenced + find rest-api-description/descriptions-next -type f -name "*.deref.json" -exec sh -c 'cp $1 ./src/rest/data/dereferenced' sh {} \; cd rest-api-description OPENAPI_COMMIT_SHA=$(git rev-parse HEAD) echo "OPENAPI_COMMIT_SHA=$OPENAPI_COMMIT_SHA" >> $GITHUB_OUTPUT @@ -61,7 +61,7 @@ jobs: - name: Decorate the dereferenced OpenAPI schemas run: | - script/rest/update-files.js --decorate-only --open-source + src/rest/scripts/update-files.js --decorate-only --open-source git status echo "Deleting the cloned github/rest-api-description repo..." rm -rf rest-api-description @@ -74,7 +74,7 @@ jobs: # If nothing to commit, exit now. It's fine. No orphans. changes=$(git diff --name-only | wc -l) if [[ $changes -eq 0 ]]; then - echo "There are no changes to commit after running lib/rest/update-files.js. Exiting..." + echo "There are no changes to commit after running src/rest/scripts/update-files.js. Exiting..." exit 0 fi diff --git a/.github/workflows/triage-unallowed-contributions.yml b/.github/workflows/triage-unallowed-contributions.yml index 0f58f95705..b0242020cd 100644 --- a/.github/workflows/triage-unallowed-contributions.yml +++ b/.github/workflows/triage-unallowed-contributions.yml @@ -16,8 +16,6 @@ on: - 'Dockerfile*' - 'src/**' - 'lib/redirects/**' - - 'lib/rest/**' - - 'lib/webhooks/**' - 'package*.json' - 'script/**' - 'content/actions/deployment/security-hardening-your-deployments/**' @@ -49,7 +47,7 @@ jobs: # Returns list of changed files matching each filter filters: | openapi: - - 'lib/rest/static/**' + - 'src/rest/data/**' notAllowed: - '.devcontainer/**' - '.github/actions-scripts/**' @@ -60,8 +58,6 @@ jobs: - 'Dockerfile*' - 'src/**' - 'lib/redirects/**' - - 'lib/rest/**' - - 'lib/webhooks/**' - 'package*.json' - 'scripts/**' - 'content/actions/deployment/security-hardening-your-deployments/**' @@ -83,8 +79,6 @@ jobs: 'Dockerfile*', 'src/**', 'lib/redirects/**', - 'lib/rest/**', - 'lib/webhooks/**', 'package*.json', 'scripts/**', 'content/actions/deployment/security-hardening-your-deployments/**', diff --git a/Dockerfile.openapi_decorator b/Dockerfile.openapi_decorator index dc25ee8a15..c4780822c7 100644 --- a/Dockerfile.openapi_decorator +++ b/Dockerfile.openapi_decorator @@ -10,11 +10,11 @@ USER node COPY --chown=node:node package.json /openapi-check COPY --chown=node:node package-lock.json /openapi-check -ADD --chown=node:node script /openapi-check/script +ADD --chown=node:node src /openapi-check/src ADD --chown=node:node lib /openapi-check/lib ADD --chown=node:node content /openapi-check/content ADD --chown=node:node data /openapi-check/data RUN npm ci -D -ENTRYPOINT ["node", "/openapi-check/script/rest/openapi-check.js"] +ENTRYPOINT ["node", "/openapi-check/src/rest/scripts/openapi-check.js"] diff --git a/content/rest/README.md b/content/rest/README.md index f04783a38e..47551192ae 100644 --- a/content/rest/README.md +++ b/content/rest/README.md @@ -5,6 +5,6 @@ The `/content/rest` directory is where the GitHub REST API docs live! * The `/content/rest/guides` and `/content/rest/overview` directories contain regular articles. These are human-editable. * The `/content/rest/reference` directory contains an article for each group of endpoints in the GitHub REST API. Most of the content in this directory is rendered using `include` tags. - The content rendered by `include` tags is sourced from the `/lib/rest/static` directory, which is automatically generated from the API source code internally in GitHub, and should not be edited by a human. For more information, see the [`/lib/rest/README.md`](/lib/rest/README.md). + The content rendered by `include` tags is sourced from the `/src/rest/data` directory, which is automatically generated from the API source code internally in GitHub, and should not be edited by a human. For more information, see the [`/src/rest/README.md`](/src/rest/README.md). **We cannot accept changes to content that is rendered by `include` tags. However, you can open an issue describing the changes you would like to see.** diff --git a/lib/all-versions.js b/lib/all-versions.js index 50de7bc051..8af2662817 100755 --- a/lib/all-versions.js +++ b/lib/all-versions.js @@ -94,7 +94,7 @@ plans.forEach((planObj) => { }) }) -const apiFilesPath = path.join(process.cwd(), 'lib/rest/static/decorated') +const apiFilesPath = path.join(process.cwd(), 'src/rest/data') // This is what determines which versions are calendar date versioned for the REST API docs // This is the source of truth for which versions are calendar date versioned. fs.readdirSync(apiFilesPath) diff --git a/middleware/api/webhooks.js b/middleware/api/webhooks.js index 3db0c3b60a..1cfa291764 100644 --- a/middleware/api/webhooks.js +++ b/middleware/api/webhooks.js @@ -1,5 +1,5 @@ import express from 'express' -import { getWebhook } from '../../lib/webhooks/index.js' +import { getWebhook } from '../../src/webhooks/lib/index.js' import { allVersions } from '../../lib/all-versions.js' import { defaultCacheControl } from '../cache-control.js' diff --git a/package.json b/package.json index ba795cbd5e..6dde79c933 100644 --- a/package.json +++ b/package.json @@ -194,7 +194,7 @@ "prettier": "prettier -w \"**/*.{ts,tsx,js,mjs,scss,yml,yaml}\"", "prettier-check": "prettier -c \"**/*.{ts,tsx,js,mjs,scss,yml,yaml}\"", "prevent-pushes-to-main": "node script/prevent-pushes-to-main.js", - "rest-dev": "script/rest/update-files.js", + "rest-dev": "src/rest/scripts/update-files.js", "show-action-deps": "echo 'Action Dependencies:' && rg '^[\\s|-]*(uses:.*)$' .github -I -N --no-heading -r '$1$2' | sort | uniq | cut -c 7-", "start": "cross-env NODE_ENV=development ENABLED_LANGUAGES=en nodemon server.js", "start-all-languages": "cross-env NODE_ENV=development nodemon server.js", diff --git a/pages/[versionId]/developers/webhooks-and-events/webhooks/webhook-events-and-payloads.tsx b/pages/[versionId]/developers/webhooks-and-events/webhooks/webhook-events-and-payloads.tsx index a005c4b74c..8e80b9b23e 100644 --- a/pages/[versionId]/developers/webhooks-and-events/webhooks/webhook-events-and-payloads.tsx +++ b/pages/[versionId]/developers/webhooks-and-events/webhooks/webhook-events-and-payloads.tsx @@ -2,7 +2,7 @@ import { GetServerSideProps } from 'next' import { useRouter } from 'next/router' import { useEffect } from 'react' -import { getInitialPageWebhooks } from 'lib/webhooks' +import { getInitialPageWebhooks } from 'src/webhooks/lib' import { getMainContext, MainContext, MainContextT } from 'components/context/MainContext' import { getAutomatedPageContextFromRequest, diff --git a/pages/[versionId]/rest/[category]/[subcategory].tsx b/pages/[versionId]/rest/[category]/[subcategory].tsx index 3220f02ff4..56c171d9df 100644 --- a/pages/[versionId]/rest/[category]/[subcategory].tsx +++ b/pages/[versionId]/rest/[category]/[subcategory].tsx @@ -1,5 +1,5 @@ import { GetServerSideProps } from 'next' -import getRest, { getRestMiniTocItems } from 'lib/rest/index.js' +import getRest, { getRestMiniTocItems } from 'src/rest/lib/index.js' import { Operation } from 'components/rest/types' import { RestReferencePage } from 'components/rest/RestReferencePage' import { getMainContext, MainContext, MainContextT } from 'components/context/MainContext' diff --git a/pages/[versionId]/rest/[category]/index.tsx b/pages/[versionId]/rest/[category]/index.tsx index d593c23506..169c07b90d 100644 --- a/pages/[versionId]/rest/[category]/index.tsx +++ b/pages/[versionId]/rest/[category]/index.tsx @@ -1,5 +1,5 @@ import { GetServerSideProps } from 'next' -import getRest, { getRestMiniTocItems } from 'lib/rest/index.js' +import getRest, { getRestMiniTocItems } from 'src/rest/lib/index.js' import nonEnterpriseDefaultVersion from 'lib/non-enterprise-default-version.js' import { Operation } from 'components/rest/types' import { RestReferencePage } from 'components/rest/RestReferencePage' diff --git a/pages/[versionId]/rest/overview/endpoints-available-for-github-apps.tsx b/pages/[versionId]/rest/overview/endpoints-available-for-github-apps.tsx index a986063cc2..75a3286f73 100644 --- a/pages/[versionId]/rest/overview/endpoints-available-for-github-apps.tsx +++ b/pages/[versionId]/rest/overview/endpoints-available-for-github-apps.tsx @@ -11,7 +11,7 @@ import { import { MainContextT, MainContext, getMainContext } from 'components/context/MainContext' import { Link } from 'components/Link' import { RestRedirect } from 'components/RestRedirect' -import { getEnabledForApps, categoriesWithoutSubcategories } from 'lib/rest/index.js' +import { getEnabledForApps, categoriesWithoutSubcategories } from 'src/rest/lib/index.js' type OperationT = { slug: string diff --git a/script/enterprise-server-deprecations/remove-static-files.js b/script/enterprise-server-deprecations/remove-static-files.js index 72ede645c5..a983ebb900 100755 --- a/script/enterprise-server-deprecations/remove-static-files.js +++ b/script/enterprise-server-deprecations/remove-static-files.js @@ -14,9 +14,9 @@ import { allVersions } from '../../lib/all-versions.js' import { deprecated } from '../../lib/enterprise-server-releases.js' const graphqlDataDir = path.join(process.cwd(), 'data/graphql') -const webhooksStaticDir = path.join(process.cwd(), 'lib/webhooks/static') +const webhooksStaticDir = path.join(process.cwd(), 'src/webhooks/data') const graphqlStaticDir = path.join(process.cwd(), 'src/graphql/data') -const restDecoratedDir = path.join(process.cwd(), 'lib/rest/static/decorated') +const restDecoratedDir = path.join(process.cwd(), 'src/rest/data') const ghesReleaseNotesDir = 'data/release-notes/enterprise-server' const supportedEnterpriseVersions = Object.values(allVersions).filter( diff --git a/script/enterprise-server-releases/create-webhook-files.js b/script/enterprise-server-releases/create-webhook-files.js index f584e93b30..8a48d96a6b 100755 --- a/script/enterprise-server-releases/create-webhook-files.js +++ b/script/enterprise-server-releases/create-webhook-files.js @@ -12,11 +12,11 @@ import path from 'path' import { program } from 'commander' import { allVersions } from '../../lib/all-versions.js' -const payloadsDir = 'lib/webhooks/static' +const payloadsDir = 'src/webhooks/data' program .description( - 'Create new payload files in lib/webhooks/static/ based on an existing version.' + 'Create new payload files in src/webhooks/data/ based on an existing version.' ) .option( '-n, --newVersion ', diff --git a/lib/rest/static/apps/enabled-for-apps.json b/src/github-apps/data/enabled-for-apps.json similarity index 100% rename from lib/rest/static/apps/enabled-for-apps.json rename to src/github-apps/data/enabled-for-apps.json diff --git a/lib/rest/README.md b/src/rest/README.md similarity index 50% rename from lib/rest/README.md rename to src/rest/README.md index 004f14950c..4167b9a814 100644 --- a/lib/rest/README.md +++ b/src/rest/README.md @@ -2,19 +2,19 @@ ## About this directory -* `lib/rest/index.js` is human-editable. -* `lib/rest/static/*.json` are generated by [scripts](../../script/rest/README.md). +* `src/rest/lib/index.js` is human-editable. +* `src/rest/data/*.json` are generated by [scripts](../../src/rest/scripts/README.md). ## Editable files -* `lib/rest/index.js` consumes the static decorated schema files and exports `categories`, `operations`, and `operationsEnabledForGitHubApps` used by the REST middleware contextualizer. +* `src/rest/lib/index.js` consumes the static decorated schema files and exports `categories`, `operations`, and `operationsEnabledForGitHubApps` used by the REST middleware contextualizer. ## Static files -Generated by `script/rest/update-files.js`: +Generated by `src/rest/scripts/update-files.js`: -* `lib/rest/static/decorated` - files generated from the dereferenced OpenAPI schema with the Markdown descriptions rendered in HTML -* `lib/rest/static/dereferenced` - **NOTE** These are only generated if you pass the --keep-dereferenced-files option and are not checked into the repository. This option is for debug only. +* `src/rest/data` - files generated from the dereferenced OpenAPI schema with the Markdown descriptions rendered in HTML +* `src/rest/data/dereferenced` - **NOTE** These are only generated if you pass the --keep-dereferenced-files option and are not checked into the repository. This option is for debug only. ## Rendering docs diff --git a/lib/rest/static/decorated/api.github.com.2022-11-28.json b/src/rest/data/api.github.com.2022-11-28.json similarity index 100% rename from lib/rest/static/decorated/api.github.com.2022-11-28.json rename to src/rest/data/api.github.com.2022-11-28.json diff --git a/lib/rest/static/decorated/ghec.2022-11-28.json b/src/rest/data/ghec.2022-11-28.json similarity index 100% rename from lib/rest/static/decorated/ghec.2022-11-28.json rename to src/rest/data/ghec.2022-11-28.json diff --git a/lib/rest/static/decorated/ghes-3.4.json b/src/rest/data/ghes-3.4.json similarity index 100% rename from lib/rest/static/decorated/ghes-3.4.json rename to src/rest/data/ghes-3.4.json diff --git a/lib/rest/static/decorated/ghes-3.5.json b/src/rest/data/ghes-3.5.json similarity index 100% rename from lib/rest/static/decorated/ghes-3.5.json rename to src/rest/data/ghes-3.5.json diff --git a/lib/rest/static/decorated/ghes-3.6.json b/src/rest/data/ghes-3.6.json similarity index 100% rename from lib/rest/static/decorated/ghes-3.6.json rename to src/rest/data/ghes-3.6.json diff --git a/lib/rest/static/decorated/ghes-3.7.json b/src/rest/data/ghes-3.7.json similarity index 100% rename from lib/rest/static/decorated/ghes-3.7.json rename to src/rest/data/ghes-3.7.json diff --git a/lib/rest/static/decorated/ghes-3.8.json b/src/rest/data/ghes-3.8.json similarity index 100% rename from lib/rest/static/decorated/ghes-3.8.json rename to src/rest/data/ghes-3.8.json diff --git a/lib/rest/static/decorated/github.ae.json b/src/rest/data/github.ae.json similarity index 100% rename from lib/rest/static/decorated/github.ae.json rename to src/rest/data/github.ae.json diff --git a/lib/rest/index.js b/src/rest/lib/index.js similarity index 90% rename from lib/rest/index.js rename to src/rest/lib/index.js index f44f303651..66c601431b 100644 --- a/lib/rest/index.js +++ b/src/rest/lib/index.js @@ -1,16 +1,14 @@ -import { fileURLToPath } from 'url' import fs from 'fs' import path from 'path' -import { readCompressedJsonFileFallback } from '../read-json-file.js' -import { getAutomatedPageMiniTocItems } from '../get-mini-toc-items.js' -import { allVersions } from '../all-versions.js' -import languages from '../languages.js' +import { readCompressedJsonFileFallback } from '../../../lib/read-json-file.js' +import { getAutomatedPageMiniTocItems } from '../../../lib/get-mini-toc-items.js' +import { allVersions } from '../../../lib/all-versions.js' +import languages from '../../../lib/languages.js' -const __dirname = path.dirname(fileURLToPath(import.meta.url)) -const schemasPath = path.join(__dirname, 'static/decorated') -const ENABLED_APPS_FILENAME = path.join(__dirname, 'static/apps/enabled-for-apps.json') -const contentPath = path.join(process.cwd(), 'content/rest') +const schemasPath = 'src/rest/data' +const ENABLED_APPS_FILENAME = 'src/github-apps/data/enabled-for-apps.json' +const contentPath = 'content/rest' /* Loads the schemas from the static/decorated folder into a single diff --git a/script/rest/README.md b/src/rest/scripts/README.md similarity index 55% rename from script/rest/README.md rename to src/rest/scripts/README.md index b8fd81173c..377cb092b6 100644 --- a/script/rest/README.md +++ b/src/rest/scripts/README.md @@ -2,15 +2,15 @@ Writers run the [update-files.js](./update-files.js) script to get the latest dereferenced OpenAPI schema files. ``` -script/rest/update-files.js +src/rest/scripts/update-files.js ``` -These scripts update the [static dereferenced OpenAPI files](../../lib/rest/static/dereferenced) to create [the decorated files](../../lib/rest/static/decorated) used to -render REST docs. See the [`lib/rest/README`](../../lib/rest/README.md) +These scripts update the dereferenced OpenAPI files to create [the decorated files](../../src/rest/data) used to +render REST docs. See the [`src/rest/README`](../../src/rest/README.md) for more info. ## Production `--decorate-only` option -When changes to the OpenAPI are merged to the default branch of the `github/github` repository, a pull request is automatically opened with the updated dereferenced OpenAPI files. When pull requests are authored by `github-openapi-bot`, a CI test runs the `lib/rest/update-files.js` script with the `--decorate-only` option. The `--decorate-only` option only decorates the dereferenced OpenAPI files, using the existing dereferenced OpenAPI schema files, and checks those changes in to the existing branch. The `--decorate-only` option is only used by a šŸ¤– and is only used on production dereferenced OpenAPI schema files. +When changes to the OpenAPI are merged to the default branch of the `github/github` repository, a pull request is automatically opened with the updated dereferenced OpenAPI files. When pull requests are authored by `github-openapi-bot`, a CI test runs the `src/rest/scripts/update-files.js` script with the `--decorate-only` option. The `--decorate-only` option only decorates the dereferenced OpenAPI files, using the existing dereferenced OpenAPI schema files, and checks those changes in to the existing branch. The `--decorate-only` option is only used by a šŸ¤– and is only used on production dereferenced OpenAPI schema files. The `.github/workflows/openapi-schema-check.yml` CI test checks that the dereferenced and decorated schema files match. If the files don't match, potential causes could be: - something went wrong when the schema changes (created by `github-openapi-bot`) were merged into another branch @@ -18,4 +18,4 @@ The `.github/workflows/openapi-schema-check.yml` CI test checks that the derefer āš ļø Only do this if you know exactly what the `--decorate-only` option does. āš ļø -If you know that the dereferenced schema files are correct, you can run the `lib/rest/update-files.js --decorate-only` command on the branch locally to update the decorated files in your branch. +If you know that the dereferenced schema files are correct, you can run the `src/rest/scripts/update-files.js --decorate-only` command on the branch locally to update the decorated files in your branch. diff --git a/script/rest/openapi-check.js b/src/rest/scripts/openapi-check.js similarity index 100% rename from script/rest/openapi-check.js rename to src/rest/scripts/openapi-check.js diff --git a/script/rest/test-open-api-schema.js b/src/rest/scripts/test-open-api-schema.js similarity index 95% rename from script/rest/test-open-api-schema.js rename to src/rest/scripts/test-open-api-schema.js index 30350f3be9..1ee7783abb 100755 --- a/script/rest/test-open-api-schema.js +++ b/src/rest/scripts/test-open-api-schema.js @@ -9,9 +9,9 @@ import fs from 'fs' import path from 'path' import _ from 'lodash' -import frontmatter from '../../lib/read-frontmatter.js' -import getApplicableVersions from '../../lib/get-applicable-versions.js' -import { allVersions, getDocsVersion } from '../../lib/all-versions.js' +import frontmatter from '../../../lib/read-frontmatter.js' +import getApplicableVersions from '../../../lib/get-applicable-versions.js' +import { allVersions, getDocsVersion } from '../../../lib/all-versions.js' const contentFiles = [] @@ -50,7 +50,7 @@ export async function getDiffOpenAPIContentRest() { } async function createOpenAPISchemasCheck() { - const schemasPath = path.join(process.cwd(), 'lib/rest/static/decorated') + const schemasPath = path.join(process.cwd(), 'src/rest/data') const openAPICheck = createCheckObj() const schemas = fs.readdirSync(schemasPath) diff --git a/script/rest/update-files.js b/src/rest/scripts/update-files.js similarity index 97% rename from script/rest/update-files.js rename to src/rest/scripts/update-files.js index e7cc03d086..0ec6982f6e 100755 --- a/script/rest/update-files.js +++ b/src/rest/scripts/update-files.js @@ -15,10 +15,10 @@ import rimraf from 'rimraf' import { decorate } from './utils/decorator.js' import { validateVersionsOptions } from './utils/get-openapi-schemas.js' -import { allVersions } from '../../lib/all-versions.js' +import { allVersions } from '../../../lib/all-versions.js' const TEMP_DOCS_DIR = path.join(process.cwd(), 'openapiTmp') -const DOCS_DEREF_OPENAPI_DIR = path.join(process.cwd(), 'lib/rest/static/dereferenced') +const DOCS_DEREF_OPENAPI_DIR = path.join(process.cwd(), 'src/rest/data/dereferenced') const GITHUB_REP_DIR = path.join(process.cwd(), '../github') program @@ -78,7 +78,7 @@ async function main() { // Decorate the dereferenced files in a format ingestible by docs.github.com await decorate(schemas) console.log( - '\nšŸ The static REST API files are now up-to-date with your local `github/github` checkout. To revert uncommitted changes, run `git checkout lib/rest/static/*`.\n\n' + '\nšŸ The static REST API files are now up-to-date with your local `github/github` checkout. To revert uncommitted changes, run `git checkout src/rest/data/*`.\n\n' ) if (!keepDereferencedFiles) { rimraf.sync(DOCS_DEREF_OPENAPI_DIR) diff --git a/script/rest/utils/create-rest-examples.js b/src/rest/scripts/utils/create-rest-examples.js similarity index 100% rename from script/rest/utils/create-rest-examples.js rename to src/rest/scripts/utils/create-rest-examples.js diff --git a/script/rest/utils/decorator.js b/src/rest/scripts/utils/decorator.js similarity index 95% rename from script/rest/utils/decorator.js rename to src/rest/scripts/utils/decorator.js index 2cc8d36c7e..eaf8afc4ba 100644 --- a/script/rest/utils/decorator.js +++ b/src/rest/scripts/utils/decorator.js @@ -3,18 +3,18 @@ import { readFile, writeFile } from 'fs/promises' import path from 'path' import { slug } from 'github-slugger' -import { allVersions } from '../../../lib/all-versions.js' -import { categoriesWithoutSubcategories } from '../../../lib/rest/index.js' +import { allVersions } from '../../../../lib/all-versions.js' +import { categoriesWithoutSubcategories } from '../../lib/index.js' import getOperations, { getWebhooks } from './get-operations.js' -const ENABLED_APPS = 'lib/rest/static/apps/enabled-for-apps.json' +const ENABLED_APPS = 'src/github-apps/data/enabled-for-apps.json' const STATIC_REDIRECTS = 'lib/redirects/static/client-side-rest-api-redirects.json' -const REST_DECORATED_DIR = 'lib/rest/static/decorated' -const WEBHOOK_DECORATED_DIR = 'lib/webhooks/static/decorated' -const REST_DEREFERENCED_DIR = 'lib/rest/static/dereferenced' +const REST_DECORATED_DIR = 'src/rest/data' +const WEBHOOK_DECORATED_DIR = 'src/webhooks/data' +const REST_DEREFERENCED_DIR = 'src/rest/data/dereferenced' export async function decorate(schemas) { - console.log('\nšŸŽ„ Decorating the OpenAPI schema files in lib/rest/static/dereferenced.\n') + console.log('\nšŸŽ„ Decorating the OpenAPI schema files in src/rest/data/dereferenced.\n') const { restSchemas, webhookSchemas } = await getOpenApiSchemaFiles(schemas) const webhookOperations = await getWebhookOperations(webhookSchemas) await createStaticWebhookFiles(webhookOperations) @@ -230,7 +230,7 @@ async function createStaticWebhookFiles(webhookSchemas) { async function getCategoryOverrideRedirects() { const { operationUrls, sectionUrls } = JSON.parse( - await readFile('script/rest/utils/rest-api-overrides.json', 'utf8') + await readFile('src/rest/scripts/utils/rest-api-overrides.json', 'utf8') ) const operationRedirects = {} @@ -253,7 +253,7 @@ async function getCategoryOverrideRedirects() { async function addRestClientSideRedirects(operations, clientSideRedirects) { // For each rest operation that doesn't have an override defined - // in script/rest/utils/rest-api-overrides.json, + // in src/rest/scripts/utils/rest-api-overrides.json, // add a client-side redirect operations.forEach((operation) => { // A handful of operations don't have external docs properties diff --git a/script/rest/utils/get-body-params.js b/src/rest/scripts/utils/get-body-params.js similarity index 99% rename from script/rest/utils/get-body-params.js rename to src/rest/scripts/utils/get-body-params.js index 17d80f13b7..38f55d7ad0 100644 --- a/script/rest/utils/get-body-params.js +++ b/src/rest/scripts/utils/get-body-params.js @@ -1,5 +1,5 @@ #!/usr/bin/env node -import renderContent from '../../../lib/render-content/index.js' +import renderContent from '../../../../lib/render-content/index.js' // If there is a oneOf at the top level, then we have to present just one // in the docs. We don't currently have a convention for showing more than one diff --git a/script/rest/utils/get-openapi-schemas.js b/src/rest/scripts/utils/get-openapi-schemas.js similarity index 97% rename from script/rest/utils/get-openapi-schemas.js rename to src/rest/scripts/utils/get-openapi-schemas.js index d834a873a8..103a53174d 100644 --- a/script/rest/utils/get-openapi-schemas.js +++ b/src/rest/scripts/utils/get-openapi-schemas.js @@ -2,7 +2,7 @@ import { readFile, readdir } from 'fs/promises' import yaml from 'js-yaml' import path from 'path' -import { allVersions } from '../../../lib/all-versions.js' +import { allVersions } from '../../../../lib/all-versions.js' const OPEN_API_RELEASES_DIR = path.join('..', 'github', '/app/api/description/config/releases') // Gets the full list of unpublished + active, deprecated + active, diff --git a/script/rest/utils/get-operations.js b/src/rest/scripts/utils/get-operations.js similarity index 100% rename from script/rest/utils/get-operations.js rename to src/rest/scripts/utils/get-operations.js diff --git a/script/rest/utils/operation-schema.js b/src/rest/scripts/utils/operation-schema.js similarity index 100% rename from script/rest/utils/operation-schema.js rename to src/rest/scripts/utils/operation-schema.js diff --git a/script/rest/utils/operation.js b/src/rest/scripts/utils/operation.js similarity index 97% rename from script/rest/utils/operation.js rename to src/rest/scripts/utils/operation.js index 88a087d6a4..e349531f2c 100644 --- a/script/rest/utils/operation.js +++ b/src/rest/scripts/utils/operation.js @@ -5,13 +5,13 @@ import { readFile } from 'fs/promises' import { get, isPlainObject } from 'lodash-es' import { parseTemplate } from 'url-template' -import renderContent from '../../../lib/render-content/index.js' +import renderContent from '../../../../lib/render-content/index.js' import getCodeSamples from './create-rest-examples.js' import operationSchema from './operation-schema.js' import { getBodyParams } from './get-body-params.js' const { operationUrls } = JSON.parse( - await readFile('script/rest/utils/rest-api-overrides.json', 'utf8') + await readFile('src/rest/scripts/utils/rest-api-overrides.json', 'utf8') ) export default class Operation { diff --git a/script/rest/utils/rest-api-overrides.json b/src/rest/scripts/utils/rest-api-overrides.json similarity index 100% rename from script/rest/utils/rest-api-overrides.json rename to src/rest/scripts/utils/rest-api-overrides.json diff --git a/script/rest/utils/webhook-schema.js b/src/rest/scripts/utils/webhook-schema.js similarity index 100% rename from script/rest/utils/webhook-schema.js rename to src/rest/scripts/utils/webhook-schema.js diff --git a/script/rest/utils/webhook.js b/src/rest/scripts/utils/webhook.js similarity index 97% rename from script/rest/utils/webhook.js rename to src/rest/scripts/utils/webhook.js index 9ddfc9e543..f835ca2cf7 100644 --- a/script/rest/utils/webhook.js +++ b/src/rest/scripts/utils/webhook.js @@ -2,7 +2,7 @@ import Ajv from 'ajv' import { get, isPlainObject } from 'lodash-es' -import renderContent from '../../../lib/render-content/index.js' +import renderContent from '../../../../lib/render-content/index.js' import webhookSchema from './webhook-schema.js' import { getBodyParams } from './get-body-params.js' diff --git a/lib/webhooks/README.md b/src/webhooks/README.md similarity index 67% rename from lib/webhooks/README.md rename to src/webhooks/README.md index 77db42151a..420a93fb70 100644 --- a/lib/webhooks/README.md +++ b/src/webhooks/README.md @@ -2,19 +2,19 @@ ## About this directory -* `lib/webhooks/index.js` is human-editable. -* `lib/rest/static/**/*.payload.json` are manually edited and copied. When a new GHES release is created, the static webhook files from the previous version's directory are copied to a new version directory. +* `src/webhooks/lib/index.js` is human-editable. +* `src/rest/data/**/*.payload.json` are manually edited and copied. When a new GHES release is created, the static webhook files from the previous version's directory are copied to a new version directory. ## Editable files -* `lib/webhooks/index.js` consumes the static JSON files in `lib/webhooks/static` and exports the data used by the REST middleware contextualizer. +* `src/webhooks/lib/index.js` consumes the static JSON files in `src/webhooks/data` and exports the data used by the REST middleware contextualizer. ## Static files -Generated by `script/rest/update-files.js`: +Generated by `src/rest/scripts/update-files.js`: -* `lib/rest/static/decorated` - files generated from the dereferenced OpenAPI schema with the Markdown descriptions rendered in HTML -* `lib/rest/static/dereferenced` - **NOTE** These are only generated if you pass the --keep-dereferenced-files option and are not checked into the repository. This option is for debug only. +* `src/rest/data` - files generated from the dereferenced OpenAPI schema with the Markdown descriptions rendered in HTML +* `src/rest/data/dereferenced` - **NOTE** These are only generated if you pass the --keep-dereferenced-files option and are not checked into the repository. This option is for debug only. ## Rendering docs diff --git a/lib/webhooks/static/decorated/api.github.com.json b/src/webhooks/data/api.github.com.json similarity index 100% rename from lib/webhooks/static/decorated/api.github.com.json rename to src/webhooks/data/api.github.com.json diff --git a/lib/webhooks/static/decorated/ghec.json b/src/webhooks/data/ghec.json similarity index 100% rename from lib/webhooks/static/decorated/ghec.json rename to src/webhooks/data/ghec.json diff --git a/lib/webhooks/static/decorated/ghes-3.3.json b/src/webhooks/data/ghes-3.3.json similarity index 100% rename from lib/webhooks/static/decorated/ghes-3.3.json rename to src/webhooks/data/ghes-3.3.json diff --git a/lib/webhooks/static/decorated/ghes-3.4.json b/src/webhooks/data/ghes-3.4.json similarity index 100% rename from lib/webhooks/static/decorated/ghes-3.4.json rename to src/webhooks/data/ghes-3.4.json diff --git a/lib/webhooks/static/decorated/ghes-3.5.json b/src/webhooks/data/ghes-3.5.json similarity index 100% rename from lib/webhooks/static/decorated/ghes-3.5.json rename to src/webhooks/data/ghes-3.5.json diff --git a/lib/webhooks/static/decorated/ghes-3.6.json b/src/webhooks/data/ghes-3.6.json similarity index 100% rename from lib/webhooks/static/decorated/ghes-3.6.json rename to src/webhooks/data/ghes-3.6.json diff --git a/lib/webhooks/static/decorated/ghes-3.7.json b/src/webhooks/data/ghes-3.7.json similarity index 100% rename from lib/webhooks/static/decorated/ghes-3.7.json rename to src/webhooks/data/ghes-3.7.json diff --git a/lib/webhooks/static/decorated/ghes-3.8.json b/src/webhooks/data/ghes-3.8.json similarity index 100% rename from lib/webhooks/static/decorated/ghes-3.8.json rename to src/webhooks/data/ghes-3.8.json diff --git a/lib/webhooks/static/decorated/github.ae.json b/src/webhooks/data/github.ae.json similarity index 100% rename from lib/webhooks/static/decorated/github.ae.json rename to src/webhooks/data/github.ae.json diff --git a/lib/webhooks/index.js b/src/webhooks/lib/index.js similarity index 90% rename from lib/webhooks/index.js rename to src/webhooks/lib/index.js index 8e6cddcccb..bf41ad3988 100644 --- a/lib/webhooks/index.js +++ b/src/webhooks/lib/index.js @@ -1,11 +1,9 @@ -import { fileURLToPath } from 'url' import path from 'path' -import { allVersions } from '../all-versions.js' -import { readCompressedJsonFileFallback } from '../read-json-file.js' +import { allVersions } from '../../../lib/all-versions.js' +import { readCompressedJsonFileFallback } from '../../../lib/read-json-file.js' -const __dirname = path.dirname(fileURLToPath(import.meta.url)) -const schemasPath = path.join(__dirname, 'static/decorated') +const schemasPath = 'src/webhooks/data' // cache for webhook data per version const webhooksCache = new Map() diff --git a/tests/meta/repository-references.js b/tests/meta/repository-references.js index 7b7c5d6547..df8d1eae1f 100644 --- a/tests/meta/repository-references.js +++ b/tests/meta/repository-references.js @@ -79,8 +79,6 @@ const ALLOW_DOCS_PATHS = [ 'contributing/search.md', 'docs/index.yaml', 'lib/excluded-links.js', - 'lib/rest/**/*.json', - 'lib/webhooks/**/*.json', 'ownership.yaml', 'script/README.md', 'script/toggle-ghae-feature-flags.js', @@ -111,7 +109,7 @@ const IGNORE_PATHS = [ '.linkinator/full.log', // Only present if you've run linkinator 'lib/search/popular-pages.json', // used to build search indexes 'tests/**/*.json', - + 'src/**/*.json', // OpenAPI schema files 'content/early-access', // Not committed to public repository. 'data/early-access', // Not committed to public repository. 'data/release-notes', // These include links to many internal issues in Liquid comments. diff --git a/tests/rendering/rest.js b/tests/rendering/rest.js index ea24b14711..e2a1e99896 100644 --- a/tests/rendering/rest.js +++ b/tests/rendering/rest.js @@ -4,15 +4,18 @@ import { readdirSync, readFileSync } from 'fs' import { join } from 'path' import { get, getDOM } from '../helpers/e2etest.js' -import getRest, { getEnabledForApps, categoriesWithoutSubcategories } from '../../lib/rest/index.js' +import getRest, { + getEnabledForApps, + categoriesWithoutSubcategories, +} from '../../src/rest/lib/index.js' import { isApiVersioned, allVersions } from '../../lib/all-versions.js' -import { getDiffOpenAPIContentRest } from '../../script/rest/test-open-api-schema.js' +import { getDiffOpenAPIContentRest } from '../../src/rest/scripts/test-open-api-schema.js' describe('REST references docs', () => { jest.setTimeout(3 * 60 * 1000) test('all category and subcategory REST pages render for free-pro-team', async () => { - const DECORATED_DIR = 'lib/rest/static/decorated' + const DECORATED_DIR = 'src/rest/data' // This currently just grabs the 'free-pro-team' schema, but ideally, we'd // get a list of all categories across all versions. const freeProTeamFile = readdirSync(DECORATED_DIR) @@ -161,7 +164,7 @@ function formatErrors(differences) { } } errorMessage += ` -This test checks that the categories and subcategories in the content/rest directory matches the decorated schemas in lib/rest/static/decorated for each version of the REST API. +This test checks that the categories and subcategories in the content/rest directory matches the decorated schemas in src/rest/data for each version of the REST API. If you have made changes to the categories or subcategories in the content/rest directory, either in the frontmatter or the structure of the directory, you will need to ensure that it matches the operations in the OpenAPI description. For example, if an operation is available in GHAE, the frontmatter versioning in the relevant docs category and subcategory files also need to be versioned for GHAE. If you are adding category or subcategory files to the content/rest directory, the OpenAPI dereferenced files must have at least one operation that will be shown for the versions in the category or subcategory files. If this is the case, it is likely that the description files have not been updated from github/github yet. diff --git a/tests/rendering/webhooks.js b/tests/rendering/webhooks.js index 9bbd93aaed..697f54497e 100644 --- a/tests/rendering/webhooks.js +++ b/tests/rendering/webhooks.js @@ -1,7 +1,7 @@ import { jest } from '@jest/globals' import { getDOM } from '../helpers/e2etest.js' import { allVersions } from '../../lib/all-versions.js' -import { getWebhooks } from '../../lib/webhooks/index.js' +import { getWebhooks } from '../../src/webhooks/lib/index.js' describe('webhooks events and payloads', () => { jest.setTimeout(300 * 1000) diff --git a/tests/unit/openapi-decorator.js b/tests/unit/openapi-decorator.js index d5b03bff95..3d63506daa 100644 --- a/tests/unit/openapi-decorator.js +++ b/tests/unit/openapi-decorator.js @@ -1,6 +1,6 @@ import { describe, expect } from '@jest/globals' -import { getOpenApiSchemaFiles } from '../../script/rest/utils/decorator.js' +import { getOpenApiSchemaFiles } from '../../src/rest/scripts/utils/decorator.js' import { allVersions } from '../../lib/all-versions.js' const supportedReleases = Object.keys(allVersions).map( diff --git a/tests/unit/openapi-examples.js b/tests/unit/openapi-examples.js index 4df2a63747..0a0decc447 100644 --- a/tests/unit/openapi-examples.js +++ b/tests/unit/openapi-examples.js @@ -1,5 +1,5 @@ import { describe, expect } from '@jest/globals' -import getCodeSamples, { mergeExamples } from '../../script/rest/utils/create-rest-examples.js' +import getCodeSamples, { mergeExamples } from '../../src/rest/scripts/utils/create-rest-examples.js' import { operation, noContent, diff --git a/tests/unit/openapi-schema.js b/tests/unit/openapi-schema.js index 472c8481b0..731dc0e04f 100644 --- a/tests/unit/openapi-schema.js +++ b/tests/unit/openapi-schema.js @@ -1,5 +1,4 @@ import fs from 'fs/promises' -import { fileURLToPath } from 'url' import path from 'path' import { describe } from '@jest/globals' @@ -7,10 +6,9 @@ import walk from 'walk-sync' import { isPlainObject, difference } from 'lodash-es' import { isApiVersioned, allVersions } from '../../lib/all-versions.js' -import getRest from '../../lib/rest/index.js' +import getRest from '../../src/rest/lib/index.js' -const __dirname = path.dirname(fileURLToPath(import.meta.url)) -const schemasPath = path.join(__dirname, '../../lib/rest/static/decorated') +const schemasPath = 'src/rest/data' async function getFlatListOfOperations(version) { const flatList = [] @@ -69,7 +67,7 @@ describe('markdown for each rest version', () => { } } - const referenceDir = path.join(__dirname, '../../content/rest') + const referenceDir = path.join('content/rest') const filenames = (await fs.readdir(referenceDir)) .filter( (filename) =>