Bug reports and feature requests may be filed on the 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.
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!
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.
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
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.
This documentation is based on the Project Hydra CONTRIBUTING guide.
- 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 --checkbefore 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.
- 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.