From f6ff2ef98e4a7da757fe41248e3af52afeb94e7b Mon Sep 17 00:00:00 2001 From: Delba de Oliveira <32464864+delbaoliveira@users.noreply.github.com> Date: Thu, 8 Jun 2023 11:01:55 +0100 Subject: [PATCH] [Next Docs] Update Git Workflow (#50579) Update our git workflow in preparation for open-sourcing the content of the docs ([linear task](https://linear.app/vercel/issue/DX-1579/set-up-github-workflow)). **Templates:** - [x] Update docs issue template to encourage contributions - [x] Update PR template to include link to new contribution guide **Code Owners / Reviewers:** - https://github.com/vercel/next.js/pull/50841 **Labels:** - [x] Add DevEx team to labeler.json so PRs get the "created by: DevEx team" **Other:** - [x] Remove docs manifest from CI checks as we no longer have one (keep the manifest for errors as they live under `/pages`) - [x] Add `unifiedjs.vscode-mdx` to the vscode extension list --- .github/ISSUE_TEMPLATE/4.docs_request.yml | 6 +++ .github/labeler.json | 15 +++++-- .github/pull_request_template.md | 6 ++- .vscode/extensions.json | 5 ++- contributing/docs/adding-documentation.md | 41 +----------------- scripts/check-manifests.js | 52 +++++++++++------------ 6 files changed, 52 insertions(+), 73 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/4.docs_request.yml b/.github/ISSUE_TEMPLATE/4.docs_request.yml index a2fe069298..67111ee7e7 100644 --- a/.github/ISSUE_TEMPLATE/4.docs_request.yml +++ b/.github/ISSUE_TEMPLATE/4.docs_request.yml @@ -4,6 +4,12 @@ title: 'Docs: ' labels: - 'template: documentation' body: + - type: markdown + attributes: + value: Before opening this issue to request a docs improvement, is this something you can help us with? Your contributions are welcomed and appreciated. See our [Docs Contribution Guide](https://nextjs.org/docs/community/contribution-guide) to learn how to edit the Next.js docs. + - type: markdown + attributes: + value: Thank you for helping us improve the docs! - type: textarea attributes: label: What is the improvement or update you wish to see? diff --git a/.github/labeler.json b/.github/labeler.json index d9c2247124..4ce7736dd6 100644 --- a/.github/labeler.json +++ b/.github/labeler.json @@ -26,7 +26,6 @@ { "type": "user", "pattern": "JanKaifer" }, { "type": "user", "pattern": "javivelasco" }, { "type": "user", "pattern": "kikobeats" }, - { "type": "user", "pattern": "leerob" }, { "type": "user", "pattern": "schniz" }, { "type": "user", "pattern": "sebmarkbage" }, { "type": "user", "pattern": "shuding" }, @@ -34,10 +33,18 @@ { "type": "user", "pattern": "timneutkens" }, { "type": "user", "pattern": "wyattjoh" } ], - "created-by: Next.js docs team": [ + "created-by: Next.js DevEx team": [ + { "type": "user", "pattern": "leerob" }, { "type": "user", "pattern": "ismaelrumzan" }, - { "type": "user", "pattern": "MaedahBatool" }, - { "type": "user", "pattern": "molebox" } + { "type": "user", "pattern": "molebox" }, + { "type": "user", "pattern": "delbaoliveira" }, + { "type": "user", "pattern": "lydiahallie" }, + { "type": "user", "pattern": "steven-tey" }, + { "type": "user", "pattern": "nutlope" }, + { "type": "user", "pattern": "stephdietz" }, + { "type": "user", "pattern": "timeyoutakeit" }, + { "type": "user", "pattern": "s3prototype" }, + { "type": "user", "pattern": "manovotny" } ], "created-by: web-tooling team": [ { "type": "user", "pattern": "alexkirsz" }, diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b898a90279..495728c63b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -4,7 +4,11 @@ Choose the right checklist for the change(s) that you're making: ## For Contributors -### Improving Documentation or adding/fixing Examples +### Improving Documentation + +- Read the Docs Contribution Guide to ensure your contribution follows the docs guidelines: https://nextjs.org/docs/community/contribution-guide + +### Adding or Updating Examples - The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md - Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 75f549ad6d..b37ae9cdb1 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -19,6 +19,9 @@ "ms-vsliveshare.vsliveshare", // Debugging - "ms-vscode.vscode-js-profile-flame" + "ms-vscode.vscode-js-profile-flame", + + // MDX Authoring + "unifiedjs.vscode-mdx" ] } diff --git a/contributing/docs/adding-documentation.md b/contributing/docs/adding-documentation.md index 3df38841d0..5067e7d3f5 100644 --- a/contributing/docs/adding-documentation.md +++ b/contributing/docs/adding-documentation.md @@ -1,40 +1,3 @@ -# Updating Documentation Paths +# Contributing to Documentation -Our documentation currently leverages a [manifest file](/docs/manifest.json), which is how documentation entries are checked. - -When adding a new entry under an existing category you only need to add an entry with `{title: '', path: '/docs/path/to/file.md'}`. The "title" is what is shown on the sidebar. - -When moving the location/url of an entry, the "title" field can be removed from the existing entry and the ".md" extension removed from the "path", then a "redirect" field with the shape of `{permanent: true/false, destination: '/some-url'}` can be added. A new entry should be added with the "title" and "path" fields if the document is renamed within the [`docs` folder](/docs) that points to the new location in the folder, e.g. `/docs/some-url.md` - -Example of moving documentation file: - -Before: - -```json -[ - { - "path": "/docs/original.md", - "title": "Hello world" - } -] -``` - -After: - -```json -[ - { - "path": "/docs/original", - "redirect": { - "permanent": false, - "destination": "/new" - } - }, - { - "path": "/docs/new.md", - "title": "Hello world" - } -] -``` - -> **Note**: The manifest is checked automatically in the "lint" step in CI when opening a PR. +See the [Docs Contribution Guide](https://nextjs.org/docs/community/contribution-guide) to learn how to contribute to the Next.js Documentation. diff --git a/scripts/check-manifests.js b/scripts/check-manifests.js index 3a1e8d929f..469479ba4d 100755 --- a/scripts/check-manifests.js +++ b/scripts/check-manifests.js @@ -19,41 +19,37 @@ function collectPaths(routes, paths = []) { } async function main() { - const manifests = ['errors/manifest.json', 'docs/manifest.json'] + const manifest = 'errors/manifest.json' let hadError = false - for (const manifest of manifests) { - const dir = path.dirname(manifest) - const files = await glob(path.join(dir, '**/*.md')) + const dir = path.dirname(manifest) + const files = await glob(path.join(dir, '**/*.md')) - const manifestData = JSON.parse( - await fs.promises.readFile(manifest, 'utf8') - ) + const manifestData = JSON.parse(await fs.promises.readFile(manifest, 'utf8')) - const paths = [] - collectPaths(manifestData.routes, paths) + const paths = [] + collectPaths(manifestData.routes, paths) - const missingFiles = files.filter( - (file) => !paths.includes(`/${file}`) && file !== 'errors/template.md' - ) + const missingFiles = files.filter( + (file) => !paths.includes(`/${file}`) && file !== 'errors/template.md' + ) - if (missingFiles.length) { + if (missingFiles.length) { + hadError = true + console.log(`Missing paths in ${manifest}:\n${missingFiles.join('\n')}`) + } else { + console.log(`No missing paths in ${manifest}`) + } + + for (const filePath of paths) { + if ( + !(await fs.promises + .access(path.join(process.cwd(), filePath), fs.constants.F_OK) + .then(() => true) + .catch(() => false)) + ) { + console.log('Could not find path:', filePath) hadError = true - console.log(`Missing paths in ${manifest}:\n${missingFiles.join('\n')}`) - } else { - console.log(`No missing paths in ${manifest}`) - } - - for (const filePath of paths) { - if ( - !(await fs.promises - .access(path.join(process.cwd(), filePath), fs.constants.F_OK) - .then(() => true) - .catch(() => false)) - ) { - console.log('Could not find path:', filePath) - hadError = true - } } }