From c2d5f0a9baf0a01067d30bccbe151ac51d4a17b1 Mon Sep 17 00:00:00 2001 From: slorber Date: Thu, 18 Jun 2020 15:48:30 +0200 Subject: [PATCH 1/4] doc(v2): publish doc update after alpha.58 release --- .gitignore | 1 + admin/publish.md | 89 +++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 73 insertions(+), 17 deletions(-) diff --git a/.gitignore b/.gitignore index c1a3bf0b1d92..5fe68e835d72 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ coverage .docusaurus .cache-loader types +test-website packages/docusaurus-utils/lib/ packages/docusaurus/lib/ packages/docusaurus-init/lib/ diff --git a/admin/publish.md b/admin/publish.md index ad95499f9751..66e7922dced4 100644 --- a/admin/publish.md +++ b/admin/publish.md @@ -1,8 +1,16 @@ # Publishing Instructions -Docusaurus is published as an npm package that can be installed via `npm` or `yarn`. Get access from the Docusaurus npm admins (@yangshun/@JoelMarcey). +Docusaurus is published as an npm package that can be installed via `npm` or `yarn`. -## Log in to npm +# Check publish rights + +Get access from the Docusaurus npm admins (@yangshun/@JoelMarcey). + +## Github + +You need publish access to use the **the main Docusaurus repository** (not a fork). + +## NPM Publishing will only work if you are logged into npm with an account with publishing rights to the package. @@ -10,25 +18,41 @@ If you are not currently logged into npm on your CLI, do the following: 1. `npm login` 1. Enter username, password and associated email address -1. Make sure you have 2FA enabled on your account (preferably just for authorization) +1. **Enable 2FA** on your account (preferably, select 2FA mode `Authorization`, not `Authorization and Publishing`) ## Docusaurus 2 -If you're publishing new v2 versions, 2FA might get in the way as the pin might expire during the publishing as there are over 10 packages to publish. You're encouraged not to use the "Authorization and Publishing" 2FA option. +If you're publishing new v2 versions, 2FA might get in the way as the pin might expire during the publishing as there are over 10 packages to publish. Use 2FA mode `Authorization`, not `Authorization and Publishing`. + +### 1. Git setup -### 0. Build skeleton website with new version (Docker required) +Use the **master branch** (up to date) of the **main Docusaurus repository** (not a fork). + +Create a new branch for the release (the branch name does not matter much): + +```sh +git co -b / +``` -To make sure that all packages will work correctly when they are published, you can build them locally and use them to run the skeleton website: +### 2. Build the project -```bash +Run `yarn install` + +It should run `yarn tsc` and build the project's packages. + +### 3. Build the skeleton website with new version (Docker required) + +To make sure that all packages will work correctly when they are published, we can initialize a new D2 skeleton website, and test that it can start/built. + +```sh yarn test:build:v2 ``` This command will build all the packages that it will publish to the running private npm proxy registry, and then initialize a new website in the `test-website` directory. Now you can start the dev server and/or make a production built. -```bash +```sh cd test-website yarn start yarn build # after manual testing in browser @@ -36,11 +60,17 @@ yarn build # after manual testing in browser If there are no errors, you can start preparing for the new release. -### 1. Update the v2 changelog +**Note**: This step is also run by the CI setup on all pull requests ([exemple](https://github.com/facebook/docusaurus/pull/2954/checks?check_run_id=780871959)) + +### 4. Update the v2 changelog + +The changelog uses Github labels to classify each pull request. Use the Github interface to assign each newly merged pull request to a Github label starting with `tag:`, otherwise the PR won't appear in the changelog. -Generate a GitHub auth token by going to https://github.com/settings/tokens. Save the token somewhere for future reference. +The `tag:` label prefix is for PRs only. Other labels are not used by the changelog tool, and it's not necessary to assign such labels to issues, only PRs. -> Before running the command below, get all tags from the original repository by running `git fetch --tags`. +Generate a GitHub auth token by going to https://github.com/settings/tokens (the only permission needed is `public_repo`). Save the token somewhere for future reference. + +Generate the changelog with: ```sh GITHUB_AUTH= yarn changelog @@ -48,7 +78,7 @@ GITHUB_AUTH= yarn changelog Copy the generated contents and paste them in `CHANGELOG-2.x.md`. -### 2. Cut a new version of the docs +### 5. Cut a new version of the docs ```sh cd website @@ -57,11 +87,26 @@ yarn run docusaurus docs:version 2.0.0-alpha.41 Test running the website with the new version locally. -### 3. Create a Pull Request +### 6. Create a Pull Request + +You should still be on your local branch `/` + +Make a commit/push, create a pull request with the changes and get it merged. + +If nobody is around for a review, just wait for the CI checks to complete, check the deploy preview, and merge it. + +An example PR would be [#2287](https://github.com/facebook/docusaurus/pull/2287). -Make a commit and create a pull request with the changes and get it merged. An example PR would be [#2287](https://github.com/facebook/docusaurus/pull/2287). Make sure the preview loads fine and is showing the new version. +### 7. Publish to npm + +Go back to the `master` branch, from which we'll do the release + +``` +git checkout master +git pull +``` -### 4. Publish to npm +**Note**: the `git pull` is useful to update `master` with your recently merged PR. Unfortunately if you are unlucky this might as well include other code from other merged PRs. In such case you should ensure the extra code works correctly, and include it in the changelog. (**TODO**: make the release process more robust?) As we have a monorepo structure, we use `lerna publish` to publish the new version of packages to npm in one shot. @@ -99,7 +144,17 @@ npm access ls-packages -If all accesses are available, build all the necessary packages with `yarn tsc`, and then you can run the command to release a new version: +It can happen that some accesses not granted, as an admin might add you to the @docusaurus NPM organisation, but you don't have access to the packages that are not in that organisation. + +Please **double-check your permissions on these 3 packages**, otherwise you'll publish a half-release and will have to release a new version. + +``` + "docusaurus": "read-write", + "docusaurus-init": "read-write", + "stylelint-copyright": "read-write" +``` + +If all accesses are available, build all the necessary packages with `yarn tsc`, and then run the command to release a new version: ```sh yarn lerna publish 2.0.0-alpha.41 --dist-tag next @@ -125,7 +180,7 @@ You should receive many emails notifying you that a new version of the packages ### 6. Notify people about new release (optional but desirable) -After new release, it was cool to notify our users about this in the Dicsord chat (`docusaurus-users` channel) and write summaries in Twiiter using the following templates. +After new release, it is cool to notify our users about this in the Dicsord chat (`docusaurus-users` channel) and write summaries on Twitter using the following templates. For Discord: From 736076870fe0fed422fb2c26348f6e3ca0855394 Mon Sep 17 00:00:00 2001 From: slorber Date: Thu, 18 Jun 2020 15:52:01 +0200 Subject: [PATCH 2/4] typo --- admin/publish.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/admin/publish.md b/admin/publish.md index 66e7922dced4..fbe62f8e48f7 100644 --- a/admin/publish.md +++ b/admin/publish.md @@ -8,7 +8,7 @@ Get access from the Docusaurus npm admins (@yangshun/@JoelMarcey). ## Github -You need publish access to use the **the main Docusaurus repository** (not a fork). +You need publish access to **the main Docusaurus repository** (not a fork). ## NPM From 21a85dd7ab6d230fc41c8d07f6beec06e5139e5f Mon Sep 17 00:00:00 2001 From: slorber Date: Thu, 18 Jun 2020 15:58:23 +0200 Subject: [PATCH 3/4] publish doc update --- admin/publish.md | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/admin/publish.md b/admin/publish.md index fbe62f8e48f7..c6f8fd6a182b 100644 --- a/admin/publish.md +++ b/admin/publish.md @@ -18,7 +18,9 @@ If you are not currently logged into npm on your CLI, do the following: 1. `npm login` 1. Enter username, password and associated email address -1. **Enable 2FA** on your account (preferably, select 2FA mode `Authorization`, not `Authorization and Publishing`) +1. **Enable 2FA** on your account (preferably for D2: select 2FA mode `Authorization`, not `Authorization and Publishing`) + +--- ## Docusaurus 2 @@ -36,14 +38,12 @@ Create a new branch for the release (the branch name does not matter much): git co -b / ``` -### 2. Build the project +### 2. Build and test the project Run `yarn install` It should run `yarn tsc` and build the project's packages. -### 3. Build the skeleton website with new version (Docker required) - To make sure that all packages will work correctly when they are published, we can initialize a new D2 skeleton website, and test that it can start/built. ```sh @@ -60,9 +60,9 @@ yarn build # after manual testing in browser If there are no errors, you can start preparing for the new release. -**Note**: This step is also run by the CI setup on all pull requests ([exemple](https://github.com/facebook/docusaurus/pull/2954/checks?check_run_id=780871959)) +**Note**: This step is also run by the CI on all pull requests ([see](https://github.com/facebook/docusaurus/pull/2954/checks?check_run_id=780871959)) -### 4. Update the v2 changelog +### 3. Update the v2 changelog The changelog uses Github labels to classify each pull request. Use the Github interface to assign each newly merged pull request to a Github label starting with `tag:`, otherwise the PR won't appear in the changelog. @@ -78,7 +78,7 @@ GITHUB_AUTH= yarn changelog Copy the generated contents and paste them in `CHANGELOG-2.x.md`. -### 5. Cut a new version of the docs +### 4. Cut a new version of the docs ```sh cd website @@ -87,7 +87,7 @@ yarn run docusaurus docs:version 2.0.0-alpha.41 Test running the website with the new version locally. -### 6. Create a Pull Request +### 5. Create a Pull Request You should still be on your local branch `/` @@ -97,7 +97,7 @@ If nobody is around for a review, just wait for the CI checks to complete, check An example PR would be [#2287](https://github.com/facebook/docusaurus/pull/2287). -### 7. Publish to npm +### 6. Build and publish to npm Go back to the `master` branch, from which we'll do the release @@ -154,13 +154,14 @@ Please **double-check your permissions on these 3 packages**, otherwise you'll p "stylelint-copyright": "read-write" ``` -If all accesses are available, build all the necessary packages with `yarn tsc`, and then run the command to release a new version: +If all accesses are available, build all the necessary packages, and then run the lerna command to release a new version: ```sh +yarn tsc yarn lerna publish 2.0.0-alpha.41 --dist-tag next ``` -_Note: The v1 packages will also be modified because it's part of the monorepo. It is not ideal but we will live with it for now._ +**Note**: The v1 packages will also be modified because it's part of the monorepo. It is not ideal but we will live with it for now.\_ This command does a few things: @@ -170,7 +171,7 @@ This command does a few things: You should receive many emails notifying you that a new version of the packages has been published. -### 5. Create a release on GitHub +### 7. Create a release on GitHub - Go to https://github.com/facebook/docusaurus/releases/new - Under the "Tag version" field, look for the newly-created tag, which is `v2.0.0-alpha.41` in this case @@ -178,7 +179,7 @@ You should receive many emails notifying you that a new version of the packages - Hit the green "Publish release" button - Profit! 💰 -### 6. Notify people about new release (optional but desirable) +### 8. Notify people about new release (optional but desirable) After new release, it is cool to notify our users about this in the Dicsord chat (`docusaurus-users` channel) and write summaries on Twitter using the following templates. @@ -211,6 +212,8 @@ NOTE: most likely this last item will be relevant for each new release, so do no https://github.com/facebook/docusaurus/releases/tag/%VER% ``` +--- + ## Docusaurus 1 1. Bump version number in [`package.json`](https://github.com/facebook/docusaurus/blob/master/package.json). From aaab5b85dd882101cff007e4e7268f21aa05171d Mon Sep 17 00:00:00 2001 From: Yangshun Tay Date: Thu, 18 Jun 2020 22:22:11 +0800 Subject: [PATCH 4/4] Update publish.md --- admin/publish.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/admin/publish.md b/admin/publish.md index c6f8fd6a182b..dded7c2be507 100644 --- a/admin/publish.md +++ b/admin/publish.md @@ -6,7 +6,7 @@ Docusaurus is published as an npm package that can be installed via `npm` or `ya Get access from the Docusaurus npm admins (@yangshun/@JoelMarcey). -## Github +## GitHub You need publish access to **the main Docusaurus repository** (not a fork). @@ -64,7 +64,7 @@ If there are no errors, you can start preparing for the new release. ### 3. Update the v2 changelog -The changelog uses Github labels to classify each pull request. Use the Github interface to assign each newly merged pull request to a Github label starting with `tag:`, otherwise the PR won't appear in the changelog. +The changelog uses GitHub labels to classify each pull request. Use the GitHub interface to assign each newly merged pull request to a GitHub label starting with `tag:`, otherwise the PR won't appear in the changelog. The `tag:` label prefix is for PRs only. Other labels are not used by the changelog tool, and it's not necessary to assign such labels to issues, only PRs.