diff --git a/contributing.md b/contributing.md index 6238e972f4bf..c1ea4cb56426 100644 --- a/contributing.md +++ b/contributing.md @@ -2,345 +2,32 @@ [Watch the 40-minute walkthrough video on how to contribute to Next.js.](https://www.youtube.com/watch?v=cuoNzXFLitc) ---- - - Read about our [Commitment to Open Source](https://vercel.com/oss). -- To contribute to [our examples](examples), please see [Adding examples](#adding-examples) below. - Before jumping into a PR be sure to search [existing PRs](https://github.com/vercel/next.js/pulls) or [issues](https://github.com/vercel/next.js/issues) for an open or closed item that relates to your submission. -## Developing - -The development branch is `canary`. This is the branch that all pull -requests should be made against. The changes on the `canary` -branch are published to the `@canary` tag on npm regularly. - -To develop locally: - -1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your - own GitHub account and then - [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device. - - If you don't need the whole git history, you can clone with depth 1 to reduce the download size (~1.6GB): - - ```sh - git clone --depth=1 https://github.com/vercel/next.js - ``` - -2. Create a new branch: - ``` - git checkout -b MY_BRANCH_NAME - ``` -3. Enable pnpm: - ``` - corepack enable pnpm - ``` -4. Install the dependencies with: - ``` - pnpm install - ``` -5. Start developing and watch for code changes: - ``` - pnpm dev - ``` -6. In a new terminal, run `pnpm types` to compile declaration files from - TypeScript. - - _Note: You may need to repeat this step if your types get outdated._ - -For instructions on how to build a project with your local version of the CLI, -see **[Developing with your local version of Next.js](#developing-with-your-local-version-of-nextjs)** -below. (Naively linking the binary is not sufficient to develop locally.) - -## Building - -You can build the project, including all type definitions, with: - -```bash -pnpm build -# - or - -pnpm prepublishOnly -``` - -By default the latest canary of the next-swc binaries will be installed and used. If you are actively working on Rust code or you need to test out the most recent Rust code that hasn't been published as a canary yet you can [install Rust](https://www.rust-lang.org/tools/install) and run `pnpm --filter=@next/swc build-native`. - -If you want to test out the wasm build locally, you will need to [install wasm-pack](https://rustwasm.github.io/wasm-pack/installer/). Run `pnpm --filter=@next/swc build-wasm --target ` to build and `node ./scripts/setup-wasm.mjs` to copy it into your `node_modules`. Run next with `NODE_OPTIONS='--no-addons'` to force it to use the wasm binary. - -If you need to clean the project for any reason, use `pnpm clean`. - -## Testing - -See the [testing readme](./test/readme.md) for information on writing tests. - -### Running tests - -```sh -pnpm testonly -``` - -If you would like to run the tests in headless mode (with the browser windows hidden) you can do - -```sh -pnpm testheadless -``` - -Running a specific test suite (e.g. `production`) inside of the `test/integration` directory: - -```sh -pnpm testonly --testPathPattern "production" -``` - -Running one test in the `production` test suite: - -```sh -pnpm testonly --testPathPattern "production" -t "should allow etag header support" -``` - -### Linting - -To check the formatting of your code: - -```sh -pnpm lint -``` - -If you get errors, you can fix them with: - -```sh -pnpm lint-fix -``` - -### Running the example apps - -Running examples can be done with: - -```sh -pnpm next ./examples/basic-css/ -``` - -To figure out which pages are available for the given example, you can run: - -```sh -EXAMPLE=./test/integration/basic -(\ - cd $EXAMPLE/pages; \ - find . -type f \ - | grep -v '\.next' \ - | sed 's#^\.##' \ - | sed 's#index\.js##' \ - | sed 's#\.js$##' \ - | xargs -I{} echo localhost:3000{} \ -) -``` - -## Developing with your local version of Next.js - -There are two options to develop with your local version of the codebase: - -### Set as a local dependency in package.json - -1. In your app's `package.json`, replace: - - ```json - "next": "", - ``` - - with: - - ```json - "next": "file:/path/to/next.js/packages/next", - ``` - -2. In your app's root directory, make sure to remove `next` from `node_modules` with: - - ```sh - rm -rf ./node_modules/next - ``` - -3. In your app's root directory, run: - - ```sh - pnpm i - ``` - - to re-install all of the dependencies. - - Note that Next will be copied from the locally compiled version as opposed to from being downloaded from the NPM registry. - -4. Run your application as you normally would. - -5. To update your app's dependencies, after you've made changes to your local `next` repository. In your app's root directory, run: - - ```sh - pnpm install --force - ``` - -#### Troubleshooting - -- If you see the below error while running `pnpm dev` with next: - -``` -Failed to load SWC binary, see more info here: https://nextjs.org/docs/messages/failed-loading-swc -``` - -Try to add the below section to your `package.json`, then run again - -```json -"optionalDependencies": { - "@next/swc-linux-x64-gnu": "canary", - "@next/swc-win32-x64-msvc": "canary", - "@next/swc-darwin-x64": "canary", - "@next/swc-darwin-arm64": "canary" -}, -``` - -### Develop inside the monorepo - -1. Move your app inside of the Next.js monorepo. - -2. Run with `pnpm next-with-deps ./app-path-in-monorepo` - -This will use the version of `next` built inside of the Next.js monorepo and the -main `pnpm dev` monorepo command can be running to make changes to the local -Next.js version at the same time (some changes might require re-running `pnpm next-with-deps` to take effect). - -## Updating documentation paths - -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 was 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. - -## Adding warning/error descriptions - -In Next.js we have a system to add helpful links to warnings and errors. - -This allows for the logged message to be short while giving a broader description and instructions on how to solve the warning/error. - -In general, all warnings and errors added should have these links attached. - -Below are the steps to add a new link: - -1. Run `pnpm new-error` which will create the error document and update the manifest automatically. -2. Add the following url to your warning/error: - `https://nextjs.org/docs/messages/`. - - For example, to link to `errors/api-routes-static-export.md` you use the url: - `https://nextjs.org/docs/messages/api-routes-static-export` - -## Adding examples - -When you add an example to the [examples](examples) directory, please follow these guidelines to ensure high quality examples: - -- TypeScript should be leveraged for new examples (no need for separate JavaScript and TypeScript examples, converting old JavaScript examples is preferred) -- Examples should not add custom ESLint configuration (we have specific templates for ESLint) -- If API routes aren't used in an example, they should be omitted -- If an example exists for a certain library and you would like to showcase a specific feature of that library, the existing example should be updated (instead of adding a new example) -- Package manager specific config should not be added (e.g. `resolutions` in `package.json`) -- In `package.json` the version of `next` (and `eslint-config-next`) should be `latest` -- In `package.json` the dependency versions should be up-to-date -- Use `export default function` for page components and API Routes instead of `const`/`let` (The exception is if the page has `getInitialProps`, in which case [`NextPage`](https://nextjs.org/docs/api-reference/data-fetching/get-initial-props#typescript) could be useful) -- CMS example directories should be prefixed with `cms-` -- Example directories should not be prefixed with `with-` -- Make sure linting passes (you can run `pnpm lint-fix`) - -Also don’t forget to add a `README.md` file with the following format: - -- Replace `DIRECTORY_NAME` with the directory name you’re adding. -- Fill in `Example Name` and `Description`. -- Examples should be TypeScript first, if possible. -- Omit the `name` and `version` fields from your `package.json`. -- Ensure all your dependencies are up to date. -- Ensure you’re using [`next/image`](https://nextjs.org/docs/api-reference/next/image). -- To add additional installation instructions, please add it where appropriate. -- To add additional notes, add `## Notes` section at the end. -- Remove the `Deploy your own` section if your example can’t be immediately deployed to Vercel. - -````markdown -# Example Name - -Description - -## Deploy your own - -Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example): - -[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/DIRECTORY_NAME&project-name=DIRECTORY_NAME&repository-name=DIRECTORY_NAME) - -## How to use - -Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example: - -```bash -npx create-next-app --example DIRECTORY_NAME DIRECTORY_NAME-app -``` - -```bash -yarn create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app -``` - -```bash -pnpm create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app -``` - -Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)). -```` - -## Publishing - -Repository maintainers can use `yarn publish-canary` to publish a new version of all packages to npm. - -## Triaging - -Repository maintainers triage every issue and PR opened in the repository. +## Repository -Issues are opened with one of these labels: +- [Triaging](./contributing/repository/triaging.md) +- [Release Channels and Publishing](./contributing/repository/release-channels-publishing.md) +- [Linting](./contributing/repository/linting.md) + -- `template: story` - a feature request, converted to an [💡 Ideas discussion](https://github.com/vercel/next.js/discussions/categories/ideas) -- `template: bug` - unverified issue with Next.js itself, or one of the examples in the [`examples`](https://github.com/vercel/next.js/tree/canary/examples) folder -- `template: documentation` - feedback for improvement or an unverified issue with the Next.js documentation +## Core -In case of a bug report, a maintainer looks at the provided reproduction. If the reproduction is missing or insufficient, a `please add a complete reproduction` label is added. If a reproduction is not provided for more than 30 days, the issue becomes stale and will be automatically closed. If a reproduction is provided within 30 days, the `please add a complete reproduction` label is removed and the issue will not become stale anymore. +- [Developing](./contributing/core/developing.md) +- [Building](./contributing/core/building.md) +- [Testing](./contributing/core/testing.md) +- [Adding Error Links](./contributing/core/adding-error-links.md) +- [Developing Using Local App](./contributing/core/developing-using-local-app.md) + -Bug reports must be verified against the `next@canary` release. The canary version of Next.js ships daily and includes all features and fixes that have not been released to the stable version yet. Think of canary as a public beta. Some issues may already be fixed in the canary version, so please verify that your issue reproduces before opening a new issue. Issues not verified against `next@canary` will be closed after 30 days. +## Documentation -If the issue is specific to the project and not to Next.js itself, it might be converted to a [🎓️ Help discussion](https://github.com/vercel/next.js/discussions/categories/help) +- [Adding Documentation](./contributing/docs/adding-documentation.md) -If the bug is verified, it will receive the `kind: bug` label and will be tracked by the maintainers. An `area:` label can be added to indicate which part of Next.js is affected. +## Examples -Confirmed issues never become stale or be closed before resolution. +- To contribute to [our examples](./examples), please see [Adding examples](./contributing/examples/adding-examples.md). -All **closed** PRs and Issues will be locked after 30 days of inactivity (eg.: comment, referencing from elsewhere). +- [Adding Examples](./contributing/examples/adding-examples.md) +- [Run Example Apps](./contributing/examples/run-example-apps.md) diff --git a/contributing/core/adding-error-links.md b/contributing/core/adding-error-links.md new file mode 100644 index 000000000000..0f6ccb3d6622 --- /dev/null +++ b/contributing/core/adding-error-links.md @@ -0,0 +1,12 @@ +# Adding Warning and Error Descriptions + +Next.js has a system to add helpful links to warnings and errors. + +This allows the logged message to be short while giving a broader description and instructions on how to solve the warning/error on the documentation. + +In general, all warnings and errors added should have these links attached. + +Below are the steps to add a new link: + +1. Run `pnpm new-error` which will create the error document and update the manifest automatically. +2. At the end of the command the URL for the error will be provided, add that to your error. diff --git a/contributing/core/building.md b/contributing/core/building.md new file mode 100644 index 000000000000..cc9950e29d75 --- /dev/null +++ b/contributing/core/building.md @@ -0,0 +1,13 @@ +# Building + +You can build Next.js, including all type definitions and packages, with: + +```bash +pnpm build +``` + +By default the latest canary of the next-swc binaries will be installed and used. If you are actively working on Rust code or you need to test out the most recent Rust code that hasn't been published as a canary yet you can [install Rust](https://www.rust-lang.org/tools/install) and run `pnpm --filter=@next/swc build-native`. + +If you want to test out the wasm build locally, you will need to [install wasm-pack](https://rustwasm.github.io/wasm-pack/installer/). Run `pnpm --filter=@next/swc build-wasm --target ` to build and `node ./scripts/setup-wasm.mjs` to copy it into your `node_modules`. Run next with `NODE_OPTIONS='--no-addons'` to force it to use the wasm binary. + +If you need to clean the project for any reason, use `pnpm clean`. diff --git a/contributing/core/developing-using-local-app.md b/contributing/core/developing-using-local-app.md new file mode 100644 index 000000000000..0d1b54e814ac --- /dev/null +++ b/contributing/core/developing-using-local-app.md @@ -0,0 +1,70 @@ +# Developing Using Your Local Version of Next.js + +There are two options to develop with your local version of the codebase: + +### Set as a local dependency in package.json + +1. In your app's `package.json`, replace: + + ```json + "next": "", + ``` + + with: + + ```json + "next": "file:/path/to/next.js/packages/next", + ``` + +2. In your app's root directory, make sure to remove `next` from `node_modules` with: + + ```sh + rm -rf ./node_modules/next + ``` + +3. In your app's root directory, run: + + ```sh + pnpm i + ``` + + to re-install all of the dependencies. + + Note that Next will be copied from the locally compiled version as opposed to from being downloaded from the NPM registry. + +4. Run your application as you normally would. + +5. To update your app's dependencies, after you've made changes to your local `next` repository. In your app's root directory, run: + + ```sh + pnpm install --force + ``` + +#### Troubleshooting + +- If you see the below error while running `pnpm dev` with next: + +``` +Failed to load SWC binary, see more info here: https://nextjs.org/docs/messages/failed-loading-swc +``` + +Try to add the below section to your `package.json`, then run again + +```json +"optionalDependencies": { + "@next/swc-linux-x64-gnu": "canary", + "@next/swc-win32-x64-msvc": "canary", + "@next/swc-darwin-x64": "canary", + "@next/swc-darwin-arm64": "canary" +}, +``` + +### Develop inside the monorepo + +1. Move your app inside of the Next.js monorepo. + +2. Run with `pnpm next-with-deps ./app-path-in-monorepo` + +This will use the version of `next` built inside of the Next.js monorepo and the +main `pnpm dev` monorepo command can be running to make changes to the local +Next.js version at the same time (some changes might require re-running `pnpm next-with-deps` to take effect). diff --git a/contributing/core/developing.md b/contributing/core/developing.md new file mode 100644 index 000000000000..b08d4c692eb0 --- /dev/null +++ b/contributing/core/developing.md @@ -0,0 +1,44 @@ +# Developing + +- The development branch is `canary`. +- All pull requests should be opened against `canary`. +- The changes on the `canary` branch are published to the `@canary` tag on npm regularly. + +To develop locally: + +1. Install the [GitHub CLI](TODO). +1. Clone the Next.js repository: + ``` + gh repo clone vercel/next.js` + ``` +1. Create a new branch: + ``` + git checkout -b MY_BRANCH_NAME origin/canary + ``` +1. Enable pnpm: + ``` + corepack enable pnpm + ``` +1. Install the dependencies with: + ``` + pnpm install + ``` +1. Start developing and watch for code changes: + ``` + pnpm dev + ``` +1. In a new terminal, run `pnpm types` to compile declaration files from + TypeScript. + _Note: You may need to repeat this step if your types get outdated._ +1. When you changes are finished commit them to the branch: + ``` + git add . + git commit -m "DESCRIBE_YOUR_CHANGES_HERE" + ``` +1. To open a pull request you can use the GitHub CLI which automatically forks and sets up a remote branch. Follow the prompts when running: + ``` + gh pr create + ``` + +For instructions on how to build a project with your local version of the CLI, +see **[Developing Using Your Local Version of Next.js](./developing-using-local-app.md)** as linking the package is not sufficient to develop locally. diff --git a/contributing/core/testing.md b/contributing/core/testing.md new file mode 100644 index 000000000000..a7ad4e46bb11 --- /dev/null +++ b/contributing/core/testing.md @@ -0,0 +1,35 @@ +# Testing + +See the [testing readme](../..//test/readme.md) for information on writing tests. + +### Running tests + +We recommend running the tests in headless mode (with the browser windows hidden) and wih a specific directory pattern (`--testPathPattern`) or test name (`-t`) which ensure only a small part of the test suite is run locally: + +For example running one test in the production test suite: + +```` +Running one test in the `test/integration/production` test suite: + +```sh +pnpm test --testPathPattern "test/integration/production" -t "should allow etag header support" +```` + +Running all tests in the `test/integration/production` test suite: + +```sh +pnpm test --testPathPattern "test/integration/production" +``` + +Running all tests (⚠️ not recommended locally): + +```sh +pnpm test +``` + +When you want to debug a particular tests you can replace `pnpm test` with `pnpm testonly` to opt-out of the headless browser. +When the test runs it will open the browser that is in the background by default, allowing you to inspect what is on the screen. + +```sh +pnpm testonly --testPathPattern "test/integration/production" -t "should allow etag header support" +``` diff --git a/contributing/core/vscode-debugger.md b/contributing/core/vscode-debugger.md new file mode 100644 index 000000000000..d75ac174bf32 --- /dev/null +++ b/contributing/core/vscode-debugger.md @@ -0,0 +1,3 @@ +# Using the VS Code Debugger + +TODO diff --git a/contributing/docs/adding-documentation.md b/contributing/docs/adding-documentation.md new file mode 100644 index 000000000000..cb7b3614c25b --- /dev/null +++ b/contributing/docs/adding-documentation.md @@ -0,0 +1,40 @@ +# Updating Documentation Paths + +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 was 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. diff --git a/contributing/examples/adding-examples.md b/contributing/examples/adding-examples.md new file mode 100644 index 000000000000..109afbbe32fb --- /dev/null +++ b/contributing/examples/adding-examples.md @@ -0,0 +1,57 @@ +# Adding Examples + +When you add an example to the [examples](examples) directory, please follow these guidelines to ensure high quality examples: + +- TypeScript should be leveraged for new examples (no need for separate JavaScript and TypeScript examples, converting old JavaScript examples is preferred) +- Examples should not add custom ESLint configuration (we have specific templates for ESLint) +- If API routes aren't used in an example, they should be omitted +- If an example exists for a certain library and you would like to showcase a specific feature of that library, the existing example should be updated (instead of adding a new example) +- Package manager specific config should not be added (e.g. `resolutions` in `package.json`) +- In `package.json` the version of `next` (and `eslint-config-next`) should be `latest` +- In `package.json` the dependency versions should be up-to-date +- Use `export default function` for page components and API Routes instead of `const`/`let` (The exception is if the page has `getInitialProps`, in which case [`NextPage`](https://nextjs.org/docs/api-reference/data-fetching/get-initial-props#typescript) could be useful) +- CMS example directories should be prefixed with `cms-` +- Example directories should not be prefixed with `with-` +- Make sure linting passes (you can run `pnpm lint-fix`) + +Also don’t forget to add a `README.md` file with the following format: + +- Replace `DIRECTORY_NAME` with the directory name you’re adding. +- Fill in `Example Name` and `Description`. +- Examples should be TypeScript first, if possible. +- Omit the `name` and `version` fields from your `package.json`. +- Ensure all your dependencies are up to date. +- Ensure you’re using [`next/image`](https://nextjs.org/docs/api-reference/next/image). +- To add additional installation instructions, please add it where appropriate. +- To add additional notes, add `## Notes` section at the end. +- Remove the `Deploy your own` section if your example can’t be immediately deployed to Vercel. + +````markdown +# Example Name + +Description + +## Deploy your own + +Deploy the example using [Vercel](https://vercel.com?utm_source=github&utm_medium=readme&utm_campaign=next-example): + +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/git/external?repository-url=https://github.com/vercel/next.js/tree/canary/examples/DIRECTORY_NAME&project-name=DIRECTORY_NAME&repository-name=DIRECTORY_NAME) + +## How to use + +Execute [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init), [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/), or [pnpm](https://pnpm.io) to bootstrap the example: + +```bash +npx create-next-app --example DIRECTORY_NAME DIRECTORY_NAME-app +``` + +```bash +yarn create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app +``` + +```bash +pnpm create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app +``` + +Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)). +```` diff --git a/contributing/examples/run-example-apps.md b/contributing/examples/run-example-apps.md new file mode 100644 index 000000000000..c95c20cd35a5 --- /dev/null +++ b/contributing/examples/run-example-apps.md @@ -0,0 +1,22 @@ +# Running Example Apps + +Running examples can be done with: + +```sh +pnpm next ./examples/basic-css/ +``` + +To figure out which pages are available for the given example, you can run: + +```sh +EXAMPLE=./test/integration/basic +(\ + cd $EXAMPLE/pages; \ + find . -type f \ + | grep -v '\.next' \ + | sed 's#^\.##' \ + | sed 's#index\.js##' \ + | sed 's#\.js$##' \ + | xargs -I{} echo localhost:3000{} \ +) +``` diff --git a/contributing/repository/linting.md b/contributing/repository/linting.md new file mode 100644 index 000000000000..1b6d5d2ac800 --- /dev/null +++ b/contributing/repository/linting.md @@ -0,0 +1,29 @@ +# Linting + +The Next.js repository runs [ESLint](TODO) and [Prettier](TODO) to lint and format all code. + +To lint all code you can run: + +```sh +pnpm lint +``` + +If you get errors, you can run the ESLint and Prettier auto-fix using: + +```sh +pnpm lint-fix +``` + +Not all rules can be auto-fixed, those require manual changes. + +## ESLint + +You can find the enabled rules in the [ESLint config](../../.eslintrc.json). + +We recommend installing the [ESLint plugin for VS Code](TODO). + +## Prettier + +We recommend installing the [Prettier plugin for VS Code](TODO). + +You can find the format configuration in the [Prettier config](../../.prettierrc.json). diff --git a/contributing/repository/pull-request-descriptions.md b/contributing/repository/pull-request-descriptions.md new file mode 100644 index 000000000000..a04cf26e3a6f --- /dev/null +++ b/contributing/repository/pull-request-descriptions.md @@ -0,0 +1,3 @@ +# Pull Request Descriptions + +TODO diff --git a/contributing/repository/release-channels-publishing.md b/contributing/repository/release-channels-publishing.md new file mode 100644 index 000000000000..5286572a418d --- /dev/null +++ b/contributing/repository/release-channels-publishing.md @@ -0,0 +1,25 @@ +# Release Channels and Publishing + +Next.js has two release channels: `stable` and `canary`. + +## Stable + +The stable release is what is installed when you `npm install next`. This channel is used by the majority of Next.js users. + +This channel is published at a regular cadence and follows [semantic versioning](TODO). + +Repository maintainers can publish a new stable version using: `pnpm publish-stable`. +The command will ask what version to publish `major`, `minor`, or `patch`. + +## Canary + +The canary channel has to be explicitly installed by users through `npm install next@canary`. + +This channel is published early based on the `canary` branch. It holds all changes that are waiting to be published to the stable channel. + +`canary` is used to test the latest features and bugfixes on real-world applications. + +By installing `next@canary` from time to time you can check if your application is affected by any changes that have not been published yet. + +Repository maintainers can publish a new stable version using: `pnpm publish-stable`. +The command will automatically decide the new version tag as it's an increment from the previous version. diff --git a/contributing/repository/triaging.md b/contributing/repository/triaging.md new file mode 100644 index 000000000000..ab9bfa7e91fe --- /dev/null +++ b/contributing/repository/triaging.md @@ -0,0 +1,21 @@ +# Triaging + +Repository maintainers triage every issue and PR opened in the repository. + +Issues are opened with one of these labels: + +- `template: story` - a feature request, converted to an [💡 Ideas discussion](https://github.com/vercel/next.js/discussions/categories/ideas) +- `template: bug` - unverified issue with Next.js itself, or one of the examples in the [`examples`](https://github.com/vercel/next.js/tree/canary/examples) folder +- `template: documentation` - feedback for improvement or an unverified issue with the Next.js documentation + +In case of a bug report, a maintainer looks at the provided reproduction. If the reproduction is missing or insufficient, a `please add a complete reproduction` label is added. If a reproduction is not provided for more than 30 days, the issue becomes stale and will be automatically closed. If a reproduction is provided within 30 days, the `please add a complete reproduction` label is removed and the issue will not become stale anymore. + +Bug reports must be verified against the `next@canary` release. The canary version of Next.js ships daily and includes all features and fixes that have not been released to the stable version yet. Think of canary as a public beta. Some issues may already be fixed in the canary version, so please verify that your issue reproduces before opening a new issue. Issues not verified against `next@canary` will be closed after 30 days. + +If the issue is specific to the project and not to Next.js itself, it might be converted to a [🎓️ Help discussion](https://github.com/vercel/next.js/discussions/categories/help) + +If the bug is verified, it will receive the `kind: bug` label and will be tracked by the maintainers. An `area:` label can be added to indicate which part of Next.js is affected. + +Confirmed issues never become stale or be closed before resolution. + +All **closed** PRs and Issues will be locked after 30 days of inactivity (eg.: comment, referencing from elsewhere). diff --git a/errors/template.txt b/errors/template.txt index 3aa3e131acac..5905279b8626 100644 --- a/errors/template.txt +++ b/errors/template.txt @@ -4,10 +4,14 @@ +{{why}} + #### Possible Ways to Fix It +{{fix}} + ### Useful Links diff --git a/package.json b/package.json index fbc7d8c6f297..7e04045b02c6 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "test-dev": "cross-env NEXT_TEST_MODE=dev pnpm testheadless", "test-start": "cross-env NEXT_TEST_MODE=start pnpm testheadless", "test-deploy": "cross-env NEXT_TEST_MODE=deploy pnpm testheadless", + "test": "cross-env HEADLESS=true pnpm testonly", "testonly": "pnpm jest --runInBand", "testheadless": "cross-env HEADLESS=true pnpm testonly", "genstats": "cross-env LOCAL_STATS=true node .github/actions/next-stats-action/src/index.js", diff --git a/plopfile.js b/plopfile.js index 44cbe6eec120..e8277c7bb19f 100644 --- a/plopfile.js +++ b/plopfile.js @@ -50,14 +50,29 @@ module.exports = function (plop) { plop.setGenerator('error', { description: 'Create a new error document', prompts: [ + { + name: 'urlPath', + type: 'input', + message: 'Url path with dashes. E.g. circular-structure', + }, { name: 'title', type: 'input', - message: 'Title for the error', + message: 'Title for the error. E.g. Circular Structure', + }, + { + name: 'why', + type: 'input', + message: 'What caused the error to happen?', + }, + { + name: 'fix', + type: 'input', + message: 'What are the possible ways to fix it?', }, ], actions: function (data) { - const fileName = getFileName(data.title) + const fileName = getFileName(data.urlPath) return [ { type: 'add', @@ -76,6 +91,7 @@ module.exports = function (plop) { return JSON.stringify(manifestData, null, 2) }, }, + `Url for the error: https://nextjs.org/docs/messages/${fileName}`, ] }, })