Contributing
============

## Bug reports and feature requests

Bug reports and feature requests may be filed on the [GitHub issue
tracker][github-issue-tracker]. When filing a bug report or feature request,
please spend a moment to look for existing issue reports and update those with
additional information if possible.

[github-issue-tracker]: https://github.com/puppetlabs/r10k/issues

### Bug reports

When filing a bug report, include as much relevant detailed information as
possible. Try to include the following:

  * A descriptive summary of the bug
  * When the bug first occurred
  * What sort of events may have triggered the bug
  * The expected behavior
  * The actual behavior
  * Steps to reproduce

If if you're seeing errors or crashes you can run R10K with the `-v debug2` to
greatly increase the log level and `--trace` to print any stack traces that may
be caught.

Including a reproduction environment with something like Vagrant is tremendously
helpful and can greatly speed up the time it takes to fix your issue!

### Feature requests

When filing a feature request, include information about how important the
feature is, how it would generally be used in your environment, and how often
this feature would be used by other users as well. Please keep in mind that
each added feature incurs additional maintenance costs, so feature requests
should strive to solve a frequent pain point for users or generally make r10k a
more effective tool for a large number of r10k users.

The policy towards feature requests in r10k has been greatly shaped by Brian
Granger's post on [features and scope in open source software][features-and-scope].

Try to include the following:

  * A descriptive summary of the feature
  * How you expect to use this feature
  * How important this feature is for your environment
  * How useful this feature would be for other users
  * Any potential caveats this may have or any issues this feature may have

[features-and-scope]: http://brianegranger.com/?p=249 "Features and Scope in Open Source Software"

## Documentation

Contributing fixes and improvements to the core documentation is a great way to
help improve R10K. Improvements to the FAQ, example code, and so forth can go a
long way towards making R10K more approachable for new users and existing users
alike. For more information about the submission process please see the section
on [code contributions](#code-contributions).

## Code contributions

This documentation is based on the Project Hydra
[CONTRIBUTING](https://github.com/projecthydra/hydra-head/blob/master/CONTRIBUTING.md)
guide.

### Making changes

  * Fork the repository on GitHub
  * Create a topic branch from where you want to base your work.
    * For new features, base your code off of 'master'.
    * For critical bugfixes, base your code off of the appropriate maintenance
      branch series, eg '1.2.x' or '1.3.x'
    * To create a new topic branch; `git checkout -b fix/master/my_contribution master`
    * Please avoid working directly on the 'master' branch.
  * Make commits of logical units.
    * Your commit message should include a high level description of your work.
  * Check for unnecessary whitespace with `git diff --check` before committing.

```
    [code/subsystem] (GH-#) Present tense short summary (80 characters or less)

    More detailed description, if necessary. It should be wrapped to 80
    characters. Try to be as descriptive as you can, even if you think that
    the commit content is obvious, it may not be obvious to others. You
    should add such description also if it's already present in bug tracker,
    it should not be necessary to visit a webpage to check the history.
```

  * Make sure you have added the necessary tests for your changes.
  * Run _all_ the tests to assure nothing else was accidentally broken.

### Submitting changes

  * Push your changes to a topic branch in your fork of the repository.
  * Submit a pull request from your fork to the project.
  * Expect to have some further discussion of your submission prior to it being merged.

Please note - code review is an essential part of the code review and submission
process. In order to keep the code base clean and maintainable questions may be
asked on implementation decisions and you may be asked to make additional
changes to the contribution. Remember - feedback is never personal and should be
given to benefit both the submitter as well as the project receiving the
contribution.
