A workflow guide for npm package authors

Releasing an npm package is like trekking through the wilderness. The ideal path will depend on how experienced you are, how much of a hurry you’re in, and whether you’re hiking alone or in a group. This post describes one way to plot a course (the best way).

Truth be told I’m writing this primarily for Future David, because I know he’ll forget the npm commands and make the same mistakes over and over again if I don’t write it all out for him. But maybe you’ll find it useful too.

Assumptions

I’m assuming you know what npm is and know how to publish a package. If I’ve assumed incorrectly, please do read npm’s Getting Started guide then come back so that I can be correct. You may also want to read npm’s Packages and Modules docs if I under-explain something.

It’s assumed that you’re using GitHub to track issues/PRs.

This post will revolve around a package called my-package that is currently on version 1.2.3.

OK let’s get into the four workflow stages:

1. Issues
2. Branches
3. Pull requests
4. Releases

1. Issues

Every piece of work on the codebase should be described in a GitHub issue. Stick to a pattern of one issue, one branch, one pull request. The aim is that years from now you can find your way from any single line of code, via git blame, to a commit, a PR, and an issue explaining the rationale behind that code.

Semver side note

Any work you do on a package is going to result in a new version, and at any point in time, a package’s next release could have one of three version numbers, according to the rules of semantic versioning.

For example, the next version of my-package (currently version 1.2.3) could be:

• 1.2.4 if it contains a fix (‘patch’)
• 1.3.0 if it contains a new feature (‘minor’)
• 2.0.0 if it contains a breaking change (‘major’)

The usual semver rules do not apply when the first number of the version is 0. This is confusing and not widely understood so you should not publish to npm with a version below 1.0.0 (npm agrees).

Some changes to the repository don’t require a version change, e.g. fixing a typo in the readme or…