Home

Nanoc»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

Nanoc is, and always will be, provided free of charge. Development is voluntary and happens entirely in free time. If you use Nanoc and like it, please consider showing your token of support by making a donation.

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.

Reviewing pull requests

We use pull requests extensively for Nanoc development. No pull request gets merged without at least one +1.

This approach ensures quality, but can be a bit slow. You can help out by checking open pull requests marked as “to review”.

If you think the pull request is good, leave a :+1:. If you have concerns, leave a comment.

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 the discussion group or find us on the IRC channel. 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

Pick the right branch to start off:

  • If you want to add a feature, use the master branch.
  • If you want to add a bug fix, use the release-4.1.x branch.

You can switch to the right branch using git checkout:

nanoc% git checkout release-4.1.x

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

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, run bundle exec rake.

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'
You can also invoke Nanoc by calling nanoc using the full path to the bin/nanoc in your cloned repository. However, we recommend using Bundler instead.

After making your modifications, 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.

Finally, create a pull request. Make sure the submit your pull request against the branch you originally started off (master or release-4.1.x).

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. Before you start, make sure that you’ve got the approval of at least one other release manager (and preferably also the approval of Denis).

Being a release manager grants you considerable power, but remember that with great power comes great responsibility.

Requirements

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

  • GitHub push access
  • RubyGems push access
  • IRC channel operator access
  • Web site push 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

Once the preparation is complete, the new version can be released. To release a new version of Nanoc, follow these steps:

  1. Build the gem (gem build nanoc.gemspec).
  2. Tag the release using git tag --sign --annotate 1.2.3 --message 'Version 1.2.3', replacing 1.2.3 with the new version number. Signing Git tags is optional, but highly recommended.
  3. Push the gem using gem push nanoc-*.gem.
  4. Push the changes to GitHub (git push). Don’t forget to also push the tags (git push --tags).

Spread the word

To announce the new release, follow these steps:

  1. Update the release notes on site. This only involves recompiling the site with the new version of Nanoc (the release notes on the site are extracted from the NEWS.md file in the Nanoc gem) and pushing the site (bundle exec nanoc deploy).
  2. Update the release notes on GitHub. Create a new release for the tag, set the release title to the new version number, and copy-paste the release notes into the description field.
  3. Send an announcement e-mail to the Nanoc mailing list. Include the version number, link to the release notes, instructions for how to update (using plain RubyGems and using Bundler), and instructions on how to report issues. The e-mail template that I often use is based off the following:
  4. Hi,
    
    Nanoc version is out. This major/minor/patch release fixes a bug related to X/adds enhancements X and Y/adds feature X. You can find the full release notes at the bottom of this e-mail or at http://nanoc.ws/release-notes/.
    
    You can update your gems using `gem update`. If you use Bundler (which I recommend), run `bundle update` to get the latest version of Nanoc.
    
    Do report any bugs you find on the GitHub issue tracker at https://github.com/nanoc/nanoc/issues/new.
    
    Cheers,
    
    Denis
    
    RELEASE NOTES
  5. Update the topic of the #nanoc IRC channel.
  6. Update the version mentioned on the Nanoc Wikipedia page.

Contributor Code of Conduct

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

This code of conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

This Code of Conduct is adapted from the Contributor Covenant, version 1.1.0, available here.

Contributors

These people have contributed to Nanoc already:

Ale Muñoz, Alexander Mankuta, Arnau Siches, Ben Armston, Bil Bas, Brian Candler, Bruno Dufour, Chris Eppstein, Christian Plessl, Colin Barrett, Colin Seymour, Croath Liu, Damien Pollet, Dan Callahan, Daniel Hofstetter, Daniel Mendler, Daniel Wollschlaeger, David Alexander, David Everitt, Dennis Sutch, Devon Luke Buchanan, Dmitry Bilunov, Eric Sunshine, Erik Hollensbe, Fabian Buch, Felix Hanley, Garen Torikian, Go Maeda, Gregory Pakosz, Grégory Karékinian, Guilherme Garnier, Jack Chu, Jake Benilov, Jasper Van der Jeugt, Jeff Forcier, Jim Mendenhall, John Nishinaga, Justin Clift, Justin Hileman, Kevin Lynagh, Louis T., Mathias Bynens, Matt Keveney, Matthew Frazier, Matthias Beyer, Matthias Reitinger, Matthias Vallentin, Michal Cichra, Nelson Chen, Nicky Peeters, Nikhil Marathe, Oliver Byford, Peter Aronoff, Raphael von der Grün, Rémi Barraquand, Remko Tronçon, Riley Goodside, Ruben Verborgh, Scott Vokes, Šime Ramov, Simon South, Spencer Whitt, Stanley Rost, Starr Horne, Stefan Bühler, Stuart Montgomery, Takashi Uchibe, Toon Willems, Tuomas Kareinen, Ursula Kallio, Vincent Driessen, Xavier Shay, Yannick Ihmels, Zaiste de Grengolada