-
Notifications
You must be signed in to change notification settings - Fork 43
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
7581049
commit dda580e
Showing
1 changed file
with
27 additions
and
31 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,46 +1,42 @@ | ||
| # Maintainers | ||
|
|
||
| This doc describes how to prep a release and publish to GitHub and `npm`. | ||
| This doc describes how releases are published to GitHub and `npm`. | ||
|
|
||
| ## Prep the Release | ||
| ## Automatic Packaging + Publishing 📦 | ||
|
|
||
| Run the following command, where `<version>` is the version you wish to update the package to: | ||
| Nearly all of our release process is automated. In this section, we discuss everything that takes place! | ||
|
|
||
| ```sh | ||
| npm run bump -- <version> | ||
| ``` | ||
| > **Note** | ||
| > You don't _need_ to know everything that takes place here, this is mostly for my own documentation purposes! But if you are tagging an actual release, there are a couple of outstanding steps that are described in [the next section](#one-more-thing-☝️) 👇 | ||
| This command will automatically bump the version in the `package.json` and the `package-lock.json` files, update [`CHANGELOG.md`](./CHANGELOG.md), and add the corresponding git tags. | ||
| When code is merged into the `main` or `next` branches, a release workflow (powered by [`semantic-release`](https://github.com/semantic-release/semantic-release)) automatically kicks off that does the following: | ||
|
|
||
| ## Publishing to GitHub :octopus: | ||
| - All commit messages since the last release are analyzed to determine whether or not the new changes warrant a new release (i.e., if the changes are features or fixes as opposed to smaller housekeeping changes) 🧐 | ||
| - Based on the changes, the version is bumped in [`package.json`](./package.json) with a new git tag 🏷️ For example, say the current version is `8.5.1` and the commit history includes a new feature. This would result in a minor semver bump, which would produce the following tags: | ||
| - A release tag like `v8.6.0` if on the `main` branch | ||
| - A prerelease tag like `v8.6.0-next.1` if on the `next` branch | ||
| - A changelog is generated and appended to [`CHANGELOG.md`](./CHANGELOG.md) 🪵 | ||
| - A build commit (like [this](https://github.com/readmeio/rdme/commit/533a2db50b39c3b6130b3af07bebaed38218db4c)) is created with the updated `package*.json` and `CHANGELOG.md` files 🆕 | ||
| - A couple duplicated tags are created for the current commit so our users can refer to them differently in their GitHub Actions (e.g., `8.6.0`, `v8`) 🔖 | ||
| - The new commit and tags are pushed to GitHub 📌 | ||
| - The new version is published to the `npm` registry 🚀 The package [distribution tag](https://docs.npmjs.com/adding-dist-tags-to-packages) will depend on which branch is being pushed to: | ||
| - If on the `main` branch, a version is pushed on the main distribution tag (a.k.a. `latest`, which is used when someone runs `npm i rdme` with no other specifiers). | ||
| - If on the `next` branch, the prerelease distribution tag (a.k.a. [`next`](https://www.npmjs.com/package/rdme/v/next)) is updated. | ||
| - A [GitHub release is created](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) for the tag (in draft form) 🐙 | ||
|
|
||
| The next step is to push these changes to GitHub: | ||
| ## One more thing ☝️ | ||
|
|
||
| ```sh | ||
| git push # pushes the code | ||
| git push --tags -f # pushes the tags | ||
| ``` | ||
| > **Note** | ||
| > The steps in this section are only required if you're building an actual release and not a prelease (i.e., changes are being merged into the `main` branch). | ||
| Once the code and tags are pushed to GitHub, [create a new release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release) so the latest tag is surfaced in [the GitHub Marketplace listing](https://github.com/marketplace/actions/rdme-sync-to-readme). | ||
| While nearly all of our release process is automated, there are a couple quick steps remaining: | ||
|
|
||
| Make sure you have the [GitHub CLI](https://cli.github.com) installed and then run the following: | ||
| 1. **Backport the changes in the `main` branch back into `next`** 🔙 you can do so by running the following: | ||
|
|
||
| ```sh | ||
| npm run release:gh | ||
| git checkout next | ||
| git merge main | ||
| git push | ||
| ``` | ||
|
|
||
| This will create a draft release which you can enhance before publishing. I like to summarize the changes and note any highlights in a blurb above the auto-generated release notes. These release links are nice for sharing with customers, on socials, etc. | ||
|
|
||
| ## Publishing to `npm` :rocket: | ||
|
|
||
| Finally, publish the changes to `npm`. If you're publishing to a non-standard [distribution tag](https://docs.npmjs.com/adding-dist-tags-to-packages) for prelease purposes or otherwise (e.g., `alpha`, `beta`, `next`, etc.), you can run the following: | ||
|
|
||
| ```sh | ||
| npm publish --tag <tag> | ||
| ``` | ||
|
|
||
| If you're publishing to the default [distribution tag](https://docs.npmjs.com/adding-dist-tags-to-packages) (i.e., `latest`), you can omit the `--tag` flag like so: | ||
|
|
||
| ```sh | ||
| npm publish | ||
| ``` | ||
| 2. **Fluff out the GitHub release and publish it** ✍️ the GitHub release is currently in draft form but it needs to be published so the latest version is surfaced to folks that discover our tool via [the GitHub Marketplace listing](https://github.com/marketplace/actions/rdme-sync-to-readme). I like to summarize the changes and note any highlights in a blurb above the auto-generated release notes. These release links are nice for sharing with customers, on socials, etc. |