From 41118a3f5512ae4a191d6c1917b058ba41a147ed Mon Sep 17 00:00:00 2001
From: Tim Neutkens <timneutkens@me.com>
Date: Fri, 2 Jul 2021 12:22:48 +0200
Subject: [PATCH] Add instructions on how to add nextjs.org/docs/messages urls

---
 .github/pull_request_template.md |  2 ++
 contributing.md                  | 16 +++++++++++++++-
 errors/template.md               | 13 +++++++++++++
 3 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 errors/template.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 28f0b8d6fadd0..9e9b995c92dd8 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -8,6 +8,7 @@ Choose the right checklist for the change that you're making:
 
 - [ ] Related issues linked using `fixes #number`
 - [ ] Integration tests added
+- [ ] Errors have helpful link attached, see `contributing.md`
 
 ## Feature
 
@@ -16,6 +17,7 @@ Choose the right checklist for the change that you're making:
 - [ ] Integration tests added
 - [ ] Documentation added
 - [ ] Telemetry added. In case of a feature if it's used or not.
+- [ ] Errors have helpful link attached, see `contributing.md`
 
 ## Documentation / Examples
 
diff --git a/contributing.md b/contributing.md
index 272de4c30562a..10638d8fed19d 100644
--- a/contributing.md
+++ b/contributing.md
@@ -14,6 +14,20 @@ Read about our [Commitment to Open Source](https://vercel.com/oss).
 
 To contribute to [our examples](examples), take a look at the [“Adding examples” section](#adding-examples).
 
+## 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:
+
+- Create a new markdown file under the `errors` directory based on `errors/template.md`: `cp errors/template.md errors/<error-file-name>.md`
+- Add the newly added file to `errors/manifest.json`
+- Add the following url to your warning/error: `https://nextjs.org/docs/messages/<file-path-without-dotmd>`. For example to link to `errors/api-routes-static-export.md` you use the url: `https://nextjs.org/docs/messages/api-routes-static-export`
+
 ## To run tests
 
 Make sure you have `chromedriver` installed for your Chrome version. You can install it with
@@ -158,4 +172,4 @@ Deploy it to the cloud with [Vercel](https://vercel.com/new?utm_source=github&ut
 
 ## Publishing
 
-Repo maintainers can use `yarn publish-canary` to publish a new version of all packages to npm.
+Repository maintainers can use `yarn publish-canary` to publish a new version of all packages to npm.
diff --git a/errors/template.md b/errors/template.md
new file mode 100644
index 0000000000000..6c038f38b2467
--- /dev/null
+++ b/errors/template.md
@@ -0,0 +1,13 @@
+# <!-- INSERT TITLE HERE -->
+
+#### Why This Error Occurred
+
+<!-- Explain why the error occured. Ensure the description makes it clear why the warning/error exists -->
+
+#### Possible Ways to Fix It
+
+<!-- Explain how to fix the warning/error, potentially by providing alternative approaches. Ensure this section is actionable by users -->
+
+### Useful Links
+
+<!-- Add links to relevant documentation -->