Development

This site is part of the DynAlp project. If you experience any issues or problems please drop us a line

Reporting bugs

If you find a bug in nanoc, you should report it! But before you do, make sure you have the latest version of nanoc (and dependencies) installed, and see if you can still reproduce the bug there. If you can, report it!

When reporting a bug, please make sure you include as many details as you can about the bug. Some information that you should include:

  • The nanoc version (nanoc --version), including the Ruby version
  • The crash.log file, if the bug you’re reporting is a crash
  • Steps to reproduce the bug

Submitting feature requests

If you have an idea for a feature that you believe is missing in nanoc, describe it on the wishlist. I recommend also starting a discussion on the discussion forums to get feedback.

The GitHub issue tracker is is used to track development of new features. Take a look at the list of open features. A bunch of old features are still described in the repository for nanoc enhancement proposals, but it is expected that these will be migrated to GitHub issues some time soon.

Contributing code

Prerequisites

First of all, you need a basic knowledge of git. The Try Git interactive tutorial is quite good for getting up to speed.

Before you start, it is worth double-checking whether what you have in mind is a good idea and would fit in nanoc. Start a thread on the discussion group or find us on the IRC channel. Generally speaking, all bug fixes are accepted, while feature changes need more discussion. Note that no matter what, backwards compatibility must be retained. This means that you cannot modify a feature to work in a different way.

Clone

If you want to contribute code, the first thing to do is get the latest source code from git. The nanoc source code is available in the nanoc repository on GitHub. Clone it:

~% git clone git://github.com/nanoc/nanoc.git

Pick the right branch

Once you have the repository, you need to pick the right branch to start off:

  • The master branch contains new developments that are scheduled to be released in the next feature release (x.Y.0 release). If your contribution is a new feature or extends an existing feature, use this branch.

  • The release-* branches, e.g. release-3.6.x, are branched off the master branch when the feature set is frozen. Bug fixes are applied on this branch and will be part of the next bugfix release (x.y.Z release). If your contribution is a bug fix, use this branch.

You can switch to the right branch using git checkout:

nanoc% git checkout release-3.6.x

Create a feature or bugfix branch

Create a branch off one of the two existing branches mentioned above. Pick a good name; the convention is to prefix the branch name with bug/ when it is a bug and with feature/ if it is a feature. Once you’ve picked a branch name, create the branch:

nanoc% git checkout -b bug/fix-colors-on-windows

Set up bundler

nanoc uses Bundler to manage its development dependencies. Run bundle install to install all dependencies necessary for development and testing:

nanoc% bundle install
Resolving dependencies...
Using rack (1.5.2)
Using adsf (1.2.0)
[snip]
Using yard (0.8.7.3)
Using bundler (1.3.5)
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.

Modify the code

Now you can make modifications to the source code.

You can find the source code in lib and the tests in test. Make sure that your changes have test cases that cover the bug fix or the new/changed functionality. To run the tests, use bundle exec rake:

nanoc% bundle exec rake

Run options: --seed 2302

# Running tests:
[snip]

To test your locally modified version of nanoc on a local nanoc site, you can either cd into the site and invoke nanoc by specifying the full path to bin/nanoc, or, if you use Bundler, edit the Gemfile and let the nanoc gem point to the locally modified version:

gem 'nanoc', :path => '/home/denis/projects/nanoc'

Make sure that the source code documentation is up-to-date. nanoc uses YARD for its source code docs. The YARD getting started guide is a helpful resource when writing YARD documentation.

Leave the NEWS.md and lib/nanoc/version.rb files untouched; they’ll be updated once a new release is about to be published.

Submit pull request

When making a pull request, pay attention to which branch you want the changed to be pulled into:

  • If your pull request is a bug fix, submit it on the latest release-3.* branch. This ensures that the bug fix comes in the next patch release.

  • If your pull request is a new feature or extends an existing feature, submit it on the master branch.

Once submitted, your work here is done. We’ll review the code, have a discussion and merge it once we’re satisfied.