mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-28 17:57:48 +02:00
chore: add npm publishing instructions (#2288)
* chore(v2): add npm publishing instructions * use headings
This commit is contained in:
Yangshun Tay
GitHub
parent
d39c301db8
commit
21f36e587f
4 changed files with 68 additions and 90 deletions
|
|
@ -2,8 +2,6 @@
|
|||
|
||||
## 2.0.0-alpha.41 (2020-02-16)
|
||||
|
||||
## Unreleased (2020-02-16)
|
||||
|
||||
#### :rocket: New Feature
|
||||
|
||||
- `docusaurus-init`, `docusaurus-preset-classic`, `docusaurus-theme-classic`
|
||||
|
|
|
|||
|
|
@ -1,27 +0,0 @@
|
|||
# Prereleasing New Version of Docusaurus
|
||||
|
||||
|
||||
|
||||
# Steps
|
||||
|
||||
1. Ensure that `origin` remote is your Docusaurus fork and `upstream` is Docusaurus original repository.
|
||||
|
||||
```bash
|
||||
$ git remote -v
|
||||
origin https://github.com/endiliey/Docusaurus.git (fetch)
|
||||
origin https://github.com/endiliey/Docusaurus.git (push)
|
||||
upstream https://github.com/facebook/docusaurus.git (fetch)
|
||||
upstream https://github.com/facebook/docusaurus.git (push)
|
||||
```
|
||||
|
||||
2. Pull latest changes from Docusaurus repository.
|
||||
|
||||
```bash
|
||||
$ git fetch upstream && git checkout master && git merge upstream/master
|
||||
```
|
||||
|
||||
2. Modify `CHANGELOG.md` and other necessary files. Do not commit the changes.
|
||||
3. Run `bash scripts/prerelease.sh`.
|
||||
4. Create your pull request on GitHub.
|
||||
|
||||
<img width="629" alt="pull request" src="https://user-images.githubusercontent.com/17883920/43393765-ccb050ac-942a-11e8-94e8-d585034fa064.PNG">
|
||||
|
|
@ -1,15 +1,71 @@
|
|||
Docusaurus is published as an npm package that can be installed via `npm` or `yarn`. Here is how you publish the package to npm:
|
||||
# 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).
|
||||
|
||||
## Log in to npm
|
||||
|
||||
Publishing will only work if you are logged into npm with an account with admin rights to the package.
|
||||
Publishing will only work if you are logged into npm with an account with publishing rights to the package.
|
||||
|
||||
If you are not currently logged into npm locally:
|
||||
If you are not currently logged into npm on your CLI, do the following:
|
||||
|
||||
1. `npm adduser`
|
||||
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)
|
||||
|
||||
## Publish
|
||||
## 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.
|
||||
|
||||
### 1. Update the v2 changelog
|
||||
|
||||
Generate a GitHub auth token by going to https://github.com/settings/tokens. Save the token somewhere for future reference.
|
||||
|
||||
```sh
|
||||
GITHUB_AUTH=<Your GitHub auth token> yarn changelog
|
||||
```
|
||||
|
||||
Copy the generated contents and paste them in `CHANGELOG-2.x.md`.
|
||||
|
||||
### 2. Cut a new version of the docs
|
||||
|
||||
```sh
|
||||
cd website
|
||||
yarn run docusaurus docs:version 2.0.0-alpha.41
|
||||
```
|
||||
|
||||
Test running the website with the new version locally.
|
||||
|
||||
### 3. Create a Pull Request
|
||||
|
||||
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.
|
||||
|
||||
### 4. Publish to npm
|
||||
|
||||
As we have a monorepo structure, we use `lerna publish` to publish the new version of packages to npm in one shot.
|
||||
|
||||
```sh
|
||||
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._
|
||||
|
||||
This command does a few things:
|
||||
|
||||
- Modifies the versions of all the `package.json` in the repository to be `2.0.0-alpha.41` and creates a commit
|
||||
- Creates a new Git tag `v2.0.0-alpha.41`
|
||||
- Pushes the new commit and Git tag to `master`
|
||||
|
||||
You should receive many emails notifying you that a new version of the packages has been published.
|
||||
|
||||
### 5. 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
|
||||
- Paste the CHANGELOG changes in the textarea below
|
||||
- Hit the green "Publish release" button
|
||||
- Profit! 💰
|
||||
|
||||
## Docusaurus 1
|
||||
|
||||
1. Bump version number in [`package.json`](https://github.com/facebook/docusaurus/blob/master/package.json).
|
||||
1. Update the [changelog](https://github.com/facebook/docusaurus/blob/master/CHANGELOG.md), including at the reference links at the bottom.
|
||||
|
|
@ -19,8 +75,14 @@ If you are not currently logged into npm locally:
|
|||
1. From the `website-1.x` directory, run `npm run docusaurus-version x.x.x`, where x.x.x is the same version number you updated to in `package.json`.
|
||||
1. Test your PR locally on a project that was created via [these instructions](https://github.com/facebook/docusaurus/blob/master/admin/local-third-party-project-testing.md).
|
||||
1. Submit your PR
|
||||
1. When your PR is merged, rebase to get the PR commit locally.
|
||||
1. When your PR is merged, rebase to get the PR commit locally
|
||||
1. Run `npm publish`
|
||||
1. Tag the commit with the new version prefixed with a `v` (e.g. `v1.19.0`) and push the tag to `master`
|
||||
1. Go to https://github.com/facebook/docusaurus/releases/new
|
||||
1. Under the "Tag version" field, look for the newly-created tag
|
||||
1. Paste the CHANGELOG changes in the textarea below
|
||||
1. Hit the green "Publish release" button
|
||||
1. Profit! 💰
|
||||
|
||||
### What version should you use?
|
||||
|
||||
|
|
|
|||
|
|
@ -1,55 +0,0 @@
|
|||
#!/usr/bin/env bash
|
||||
|
||||
##
|
||||
# Copyright (c) 2017-present, Facebook, Inc.
|
||||
#
|
||||
# This source code is licensed under the MIT license found in the
|
||||
# LICENSE file in the root directory of this source tree.
|
||||
#
|
||||
|
||||
DOCS_VERSION_COMMAND="run docusaurus-version"
|
||||
|
||||
echo "Select an option for release："
|
||||
echo
|
||||
|
||||
select VERSION in patch minor major "Specific Version"
|
||||
do
|
||||
echo
|
||||
if [[ $REPLY =~ ^[1-4]$ ]]; then
|
||||
if [[ $REPLY == 4 ]]; then
|
||||
read -p "Enter a specific version: " -r VERSION
|
||||
echo
|
||||
if [[ -z $REPLY ]]; then
|
||||
VERSION=$REPLY
|
||||
fi
|
||||
fi
|
||||
|
||||
read -p "Create $VERSION commit - Are you sure ... (y/n) " -n 1 -r
|
||||
echo
|
||||
|
||||
if [[ $REPLY =~ ^[Yy]$ || -z $REPLY ]]; then
|
||||
# Bump version
|
||||
cd packages/docusaurus-1.x
|
||||
yarn version --new-version $VERSION --no-git-tag-version
|
||||
NEW_VERSION=$(node -p "require('./package.json').version")
|
||||
|
||||
# Create new branch
|
||||
git checkout -B $NEW_VERSION master
|
||||
# Cut docusaurus docs version
|
||||
cd ../../website-1.x && yarn $DOCS_VERSION_COMMAND $NEW_VERSION
|
||||
|
||||
# Create commit
|
||||
git add ../
|
||||
git commit -m "v$NEW_VERSION"
|
||||
git push -f origin $NEW_VERSION
|
||||
echo "Finished"
|
||||
else
|
||||
echo Cancelled
|
||||
fi
|
||||
break
|
||||
else
|
||||
echo Invalid \"${REPLY}\"
|
||||
echo "To continue, please enter one of the options (1-4):"
|
||||
echo
|
||||
fi
|
||||
done
|
||||
Loading…
Add table
Reference in a new issue