Tools and Strategies for node.js Development on GitHub

octocat When developing open source node.js projects on GitHub, there are tools and strategies which you can use to streamline development and increase the quality of your repo. In this post, I will share what I have learned about these topics during my experience on GitHub.

Continuously Integrating new code

If you have tests for your project, you will want them run whenever a commit is pushed to your repo or a pull request is proposed. Instead of manually pulling down new code and running the tests yourself, you can use Travis CI to automatically run your test suite in a clean environment. This helps you determine if new code breaks existing functionality and lets you merge branches and pull requests without having to test them locally.

Once your repo is integrated with Travis, pull requests will include a message stating if the test suite passed or failed. The following message will appear if the test suite passes: TravisBuild

Getting Travis integrated with your repo

To get Travis integrated with your repo, first add the following .travis.yml file to your root folder:

language: node_js
node_js:
  - "0.10"
  - "0.8"
notifications:
  email: false

The first and second properties of this file tell Travis to run your tests in node versions .10 and .8. The final property opts out of email notifications which you likely won't want initially.

After adding the .travis.yml to your repo, sign into Travis, then sync your repo. Now on every commit, Travis will run the commands listed in the before_script property and then run your package.json's scripts.test property as a terminal command.

Travis Status Badge

Build Status

You should also get a Travis status badge for your repo so that contributors will know if the latest commit in master passed the test suite.

Keeping up with dependencies

Dependency Status

Keeping up with dependencies is no fun. Using gemnasium, you can have a badge in your README which will alert contributors when your project's dependencies are out of date.

Displaying your module's latest version in npm

NPM version

Using Gemfury you can get a badge to display the latest version of your project in npm. This is helpful for contributors to see what version of your code was last pushed to npm and for visitors to easily check if they have the latest version.

Changelog

When a contributor shows up to your repo, it is helpful to have a Changelog where they can track the changes that have been made for each new version of your project. This is especially helpful for debugging issues because you can easily trace the history of your project's features.

Here is an example Changelog:

0.1.0 - Altered post api to expose all properties on a post object.

0.0.1 - Added bug fix for posts with special characters.

0.0.0 - Initial release.

I usually put the Changelog at the bottom of my README.md, but I have seen people also use a CHANGELOG.md or HISTORY.md file for larger projects.

Semantic Versioning

When semanticly versioning your project, users will automatically get new versions with bug fixes & patches but not versions with API breaking changes. Before looking into the usage of semantic versioning, it is important to understand why you would want to version your module in a specific way.

Behavior of --save'd modules

When saving installed modules from npm using the --save or --save-dev flags, the default behavior is to have a ~ in front of the module's version number in the package.json. This ~ prefix will pick up new patch versions which modify the final section of the version number. For example, if there were the following versions available for a module: 0.0.1, 0.0.2, and 0.1.0 and a project had ~0.0.1 specified in its package.json, when someone runs npm install from a clean folder they would get version 0.0.2.

Semantic Versioning in practice

The important thing to do as a node.js module author is to update the second number, or minor version, for API breaking changes and edit the third number, or patch version, for bug fixes. When users get new patch versions because of the ~ in front of your module's version number, it should not break their current usage of the module.

Note: Changing the minor version for API-breaking changes only occurs before the stable public API or 1.0.0 release. Refer to the semantic versioning document when releasing the stable public API.

README

Blockquote project summary

Brightens your day by opening a browser tab to a music video

When showing up to a project, potential users want to quickly determine what it offers them. Using a markdown blockquote at the top of your README is a clear way to display a summary of your project to a new user.

Minimal Usage

Once you've convinced the user to try out your project, it is valuable to give them instructions of how to use it with minimal configuration. Later in your documentation you can embellish in more extensive examples, but it is important to get a new user started quickly so that they get invested in the project.

Explicity define the API

Users don't want to look at your source code to learn how to use your project. By explicitly defining parameter types, descriptions, and default values(if any) of your methods parameters/properties, you can save yourself time responding to issues submitted by confused users. I like to use the same syntax as the node.js docs when defining methods, here is an example method definition for mymodule:

mymodule(inputString, [color], [callback])

When defining parameters, I like to first define its type, then any default values, then describe it. Sometimes the parameter warrants an example use case to illustrate its usage relative to other parameters. Here are example parameter definitions for mymodule:

inputString

Type: String

Description of the inputString parameter.

color

Type: String Default: 'blue'

Description of the color parameter.

callback

Type: Function

Description of the callback parameter. This parameter can be used as the second parameter if the color is omitted. Here is an example which illustrates this usage:

mymodule('Hello World!', function () {
  console.log('I am in a callback :)');
});

Issue Driven Development

Issues are the most transparent way to keep track of a project's development. They are a great place to solicit feedback from contributors and users before implementing new features, as well as a place to track to-dos. Having issues on a project that suggest future development invites new contributors to get involved and resolve those issues.

Conclusion

I hope these tips help you improve your open source workflow and create sexy repos :). See you on GitHub!