Contributing

Nanoc is the effort of dozens of people. Contributions are welcomed, no matter how small. This page shows the different ways you can make a difference to Nanoc.

Making a donation

If you like Nanoc and would like to financially support its development, please leave a tip on Denis’ Ko-fi page. Thank you so much!

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 new feature, start a discussion on the Nanoc Google group.

Contributing code

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

Before you start coding, make sure that the idea you have fits with Nanoc’s philosophy. Start a thread on GitHub discussions or on the Google group. Generally speaking, all bug fixes are accepted, while feature changes need more discussion.

For all changes, backwards compatibility must be retained. This means that you can add a feature, but you cannot modify a feature to work in a different way.

To fetch the latest Nanoc source code, clone the Git repository:

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

Create a new branch. 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

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

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, do one of the following:

  • To run all tests, run bundle exec rake.
  • To run style checks, run bundle exec rake rubocop.
  • To run a specific test file, run bundle exec m path_to_test_file from a subdirectory.
  • To run a specific spec file, run bundle exec rspec path_to_spec_file from a subdirectory.

To test your locally modified version of Nanoc on a local Nanoc site, edit your site’s Gemfile and let the Nanoc gem point to the locally modified version:

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

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

Releasing Nanoc

If you’re a release manager, you can follow these steps to release a new version of Nanoc.

Requirements

Before you start, ensure that you have access to the following:

  • GitHub push access
  • RubyGems push access
  • Twitter access

If you are missing any of these, let me (Denis) know and I’ll set you up.

Preparing for a release

Preparing a release means ensuring that the version that is about to be released meets the requirements. To prepare for a release, follow these steps:

  1. Ensure the Nanoc::VERSION constant is set to the right version. Keep in mind that Nanoc follows the Semantic Versioning standard.
  2. Ensure the release notes in the NEWS.md file are up-to-date, and that the release date is correct.
  3. Run the tests using bundle exec rake.
  4. As a final check, compile the Nanoc site with the Nanoc gem in the Gemfile pointing to your local Nanoc working copy, and verify locally that the release notes page is as expected.

Releasing the new version

Run scripts/release. It should just work!

Spread the word

To announce the new release, follow these steps:

  1. In the nanoc.ws repository, upgrade Nanoc. The web site will be built and published automatically.
  2. Send a tweet from the @nanoc_ssg Twitter account.
  3. Update the version mentioned on the Nanoc Wikipedia page.

Contributor code of conduct

Contribution is governed by the code of conduct.