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.jsonfile. - 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 pushing your release to GitHub:
gren --action=changelog --generate --tags=allto 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 -fto push the rebase'd version of your repo