docs(v2): document canary releases (#4987)

website/community/3-contributing.md

@@ -54,6 +54,10 @@ You can also file issues as [feature requests or enhancements](https://github.co
 
 Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe disclosure of security bugs. With that in mind, please do not file public issues; go through the process outlined on that page.
 
+### Testing new features
+
+You can become an early adopter of new features by using the [`@canary` npm dist tag](/community/canary) and test new features on your site as soon as the pull-request is merged. This helps us catch problems before the official release.
+
 ## Working on Docusaurus code {#working-on-docusaurus-code}
 
 ### Installation {#installation}

website/community/4-canary.md

@@ -0,0 +1,64 @@
+# Canary releases
+
+Docusaurus has a canary releases system.
+
+It permits you to **test new unreleased features** as soon as the pull-requests are merged.
+
+It is a good way to **give feedback to maintainers**, ensuring the newly implemented feature works as intended.
+
+:::note
+
+Using a canary release in production might seem risky, but in practice it's not.
+
+A canary release passes all automated tests, and is used in production by the Docusaurus site itself.
+
+:::
+
+## Canary npm dist tag
+
+For any code-related commit on `master`, the continuous integration will publish a canary release under the `@canary` npm dist tag. It generally takes up to 10 minutes.
+
+You can see on [npm](https://www.npmjs.com/package/@docusaurus/core?activeTab=versions) the current dist tags:
+
+- `latest`: stable releases (example: `2.0.0-beta.0`)
+- `canary`: canary releases (example: `2.0.0-beta.4a6de5cf7`)
+
+:::tip
+
+Make sure to use the latest canary release and check the publication date (sometimes the publish process fails).
+
+:::
+
+## Using a canary release
+
+Take the latest version published under the [canary npm dist tag](https://www.npmjs.com/package/@docusaurus/core?activeTab=versions) (for example: `2.0.0-beta.4a6de5cf7`).
+
+Use it for all the `@docusaurus/*` dependencies in your `package.json`:
+
+```diff
+-  "@docusaurus/core": "^2.0.0-beta.0",
+-  "@docusaurus/preset-classic": "^2.0.0-beta.0",
++  "@docusaurus/core": "2.0.0-beta.4a6de5cf7",
++  "@docusaurus/preset-classic": "2.0.0-beta.4a6de5cf7",
+```
+
+Then, install the dependencies again and start your site:
+
+```bash npm2yarn
+npm install
+npm start
+```
+
+You can also upgrade the `@docusaurus/*` packages with a command line:
+
+```bash npm2yarn
+npm install --save-exact @docusaurus/core@canary @docusaurus/preset-classic@canary
+```
+
+:::caution
+
+Make sure to include all the `@docusaurus/*` packages.
+
+For canary releases, prefer using an exact version instead of a semver range (avoid the `^` prefix).
+
+:::

website/docs/installation.md

@@ -154,6 +154,12 @@ Alternatively, if you are using Yarn, you can do:
 yarn upgrade @docusaurus/core@2.0.0-beta.0 @docusaurus/preset-classic@2.0.0-beta.0
 ```
 
+:::tip
+
+Use new unreleased features of Docusaurus with the [`@canary` npm dist tag](/community/canary)
+
+:::
+
 ## Problems? {#problems}
 
 Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/docusaurus) or [Twitter](https://twitter.com/docusaurus).