Releasing Packages to GitHub and the npm Registry

Photo by PaaZ PG on Unsplash

This publication describes a simple process I follow to tag and release a new package version to GitHub and the npm Registry. I am sharing this publication because I believe others can use this process as a guideline, while modifying certain steps as they see fit.

For simplicity, this publication assumes that you have already published your package on the npm Registry and also assumes that you are working off of at least 2 GitHub branches: develop and main. develop being the branch that is undergoing development, and main being the production branch.

When you are ready to release a new version of your package, follow the steps below.

1. Checkout the develop branch and pull latest:
   git checkout develop && git pull
2. Create release branch from the develop branch, replacing <YYYY.MM.DD> with today's date. I.e. 2023.06.06:
   git checkout -b release/<YYYY.MM.DD>
Note: For multiple releases on the same day, add a hyphen followed by a letter. I.e. release/2023.06.06-b.
3. Update package.json version, replacing <update_type> with one of the semantic versioning release types (major, minor, or patch):
   npm — no-git-tag-version version <update_type>
4. Add appropriate release notes to CHANGELOG.md file and add version number from package.json file
5. Commit CHANGELOG.md and package.json files, replacing <YYYY.MM.DD> with today's date. I.e. 2023.06.06:
   git add -A && git commit -m ‘release <YYYY.MM.DD>’
6. Push to origin release branch, replacing <branch_name> with the branch name that you created in step 2. I.e. release/2023.06.06:
   git push -u origin <branch_name>
7. Create pull request from the release branch to the develop branch
8. Merge (without squashing) pull request and delete release branch from GitHub
9. Create and merge (without squashing) pull request from the develop branch to the main branch
10. Checkout the main branch locally and pull latest:
    git checkout main && git pull
    Note: It’s good practice to ensure that you are working on a clean main branch. To ensure that you have not made any unexpected changes locally to the main branch, run git status.
11. Prepare the package for publishing. This includes transpiling or compiling a new distributed build, linting, and compiling assets.
12. Create and push tag, replacing <version_number> with version number from CHANGELOG.md and package.json files:
    git tag -a v<version_number> -m ‘version <version_number>’ && git push — tags
    Note: Take notice of the “v” prefix when creating GitHub tags in the command above. I.e. v1.0.0.
13. Log in to your npm Registry account:
    npm login
14. Publish on the npm Registry:
    npm publish — access public
15. Checkout the develop branch locally and merge the main branch into it so that the two branches are up-to-date:
    git checkout develop && git pull && git merge main
    Note: It’s good practice to ensure that you are working on a clean develop branch. To ensure that you have not made any unexpected changes locally to the develop branch, run git status before merging in main.
16. Push updated develop branch to origin develop:
    git push
17. And finally, publish a release on GitHub by going to https://github.com/<github-account>/<github-repository>/releases/new, replacing <github-account> and <github-repository> with the appropriate values