This doc attempts to capture some of the more nuanced tips and tricks involved in managing an NPM-based open source project, specifically with an eye toward maintaining a structured release process that limits the pain and surprises you cause your audience.
Contrary to the title, this guide is going to assume you're not an idiot. In fact, a working knowledge of git, GitHub, and NPM are assumed. Moreover, we're going to gloss over the basic steps involved in creating a project and instead focus on the less-obvious aspects of how you maintain a project. So, things this guide assumes you've done before you got here:
- Write some useful code
- Create a github repo for it
- Create and authorize your npm account
- Write a
package.json
file. - Publish your project as an NPM module
Users care about what's changed and what's changing.
As the maintainer of a project, one of your jobs is to document the changes between releases. To that end, use the Github Flow when developing. Creating branches and PRs may seem unnecessary, but it's good practice, and PRS (not commits) are the basis for documentation. In addition, you should also get in the habit of creating an Issue for any major changes you expect to make. Note only will this make your project's Issues and PR pages a useful source of information, it enables tools like github-release-notes
to auto-generate changelog and release notes. (More on this below)
npm version
is your friend. It takes care of 3 slightly-onerous tasks in a single, simple, command:
- Bump the version number in
package.json
- Commit the change to your local repo
- Create an appropriately named version tag
Note: Be sure to bump your version number in accordance with Semantic Versioning rules. Failing to do this is great way to piss off your users.
Use git push
the commit and tag created by npm version
to your GitHub repo
Use npm publish
to publish your new version to NPM.
Voila, you're done... or not.
Maintaining a change log and release notes is optional, but good practice. It's also a bit of a hassle. This is where an automated tool like github-release-notes can make your life easier. I'd refer you to the docs for that project, but they're a little unclear at the moment. Here's the flow I'm currently using, but I'm not sure how correct this is:
Prior to git push
ing your release to GitHub:
gren --action=changelog --generate --tags=all
to auto-generate CHANGELOG.mdgit commit -am "Update CHANGELOG.md"
git rebase -i HEAD~2
, then reverse order of commits to have CHANGELOG update included with taggit push -f
to push the rebase'd version of your repo