diff --git a/website/community/3-contributing.md b/website/community/3-contributing.md index 40b81e88dc..a5282ee9d1 100644 --- a/website/community/3-contributing.md +++ b/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} diff --git a/website/community/4-canary.md b/website/community/4-canary.md new file mode 100644 index 0000000000..176a4b9e63 --- /dev/null +++ b/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). + +::: diff --git a/website/docs/installation.md b/website/docs/installation.md index 40db5aef34..b91dc43ac2 100644 --- a/website/docs/installation.md +++ b/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).