Dependency Management Best Practices

When I familiarize myself with a newly inherited project or open source package, one of my first steps is to read over the project’s dependencies. In ruby’s case, this is almost always in the form of a Bundler Gemfile. These files tend to be a dumping ground for developers, with gems haphazardly added. To combat this, I’ve crafted a list of best practices to use when setting up a project.

Note: Although these recommendations are demonstrated in ruby, several are applicable to other technology stacks (e.g., Node NPM package.json, .NET NuGet packages.config, Python PIP requirements.txt).

Ruby Version: Declare the specific version of ruby at the top of the file.

Screen Shot 2015-11-03 at 11.19.22 AM
 

Comments: Leave any/all comments to the right of each gem declaration.
Sourced Dependencies:List your sourced dependencies at the top of each group. These gems should be regularly checked to see if they can be switched to a specific version (e.g., waiting for a pull request).

Screen Shot 2015-11-03 at 11.19.14 AM
 

Groups: When adding a dependency, consider its purpose before placing it in the default group. If a dependency is only being used for a specific environment, the Gemfile should reflect that, and not just with a comment beside the dependency.

Screen Shot 2015-11-03 at 11.19.04 AM

Group Order: Devise a standard order to your dependency groups. Here is a recommended order:

  • :default
  • :production
  • :staging, :beta (other misc. environment groups)
  • :assets
  • :test
  • :test, :development
  • :development

Order: Alphabetize the gems in a given dependency group. This makes it easy to find specific gems, whether you’re making an update or simply reading the Gemfile.

Screen Shot 2015-11-03 at 11.18.52 AM

Gemfile.lock: If you don’t have this checked into source control, stop reading and add it NOW. Ask questions later.For reference, I’ve provided the before and after of the Gemfile for a current project.

Before:

After:

Winton DeShong

Technical Lead

Published on November 13, 2015