Contributing to Puppet Labs Modules¶
How to contribute¶
Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
- Make sure you have a GitHub account.
- Submit a ticket for your issue, assuming one does not already exist.
- See each module on the Puppet Forge for its issue tracker.
- Please try to clearly describe the issue, including the steps to reproduce any bug.
- Please include the story of “why” you want to do something.
- Fork the repository on GitHub.
- Glance at the Git Best Practices document, even if you don’t read it all yet.
- If this is a new feature, make sure you discuss it on the puppet-users mailing list before getting started on code.
How to Get Help¶
We really want modules to be simple to contribute to, and to ensure that you can get started quickly. A big part of that is being available to help you figure out the right way to solve a problem, and to make sure you get up to speed quickly.
You can always reach out and ask for help:
- by email or through the web on the email@example.com mailing list. (membership is required to post.)
- by IRC, through #puppet on the FreeNode IRC network.
Discuss Your Change¶
You should start by discussing your change in public: * for small but clear changes, [open an issue describing the bug or feature][bugs]. * for larger changes, send an email to firstname.lastname@example.org or [post through the web][puppet-dev] before creating the issue.
Any and all members of the community can respond to an issue, and make comments or suggestions. You should take these comments seriously, but you are not obliged to do what they say.
If the issue is going in the wrong direction, one of the project leaders will comment within 14 days, so that you don’t waste time building a solution that won’t be accepted. If you don’t get a response you can @mention a committer in a GitHub message, or CC a committer to the discussion thread.
While we love getting code submitted to our projects, the act of submitting code does not guarantee it will be merged. This is why we encourage discussion prior to code submissions.
- Create a topic branch for your work.
- You should branch off the
masterbranch unless otherwise specified by the specific module.
- Name your branch by the type of contribution and target:
- Generally, the type is
feature, but if they don’t fit pick something sensible.
- Generally, the type is
- To create a topic branch based on master:
git checkout master && git pull && git checkout -b bug/master/my_contribution
- Don’t work directly on the
masterbranch, or any other core branch. Your pull request will be rejected unless it is on a topic branch.
- Every commit should do one thing, and only one thing.
- Having too many commits is better than having too few commits.
- Check for unnecessary whitespace with
git diff --checkbefore committing.
- Make sure your commit messages are in the proper format.
(#99999) Make the example in CONTRIBUTING imperative and concrete Without this patch applied the example commit message in the CONTRIBUTING document is not a concrete example. This is a problem because the contributor is left to imagine what the commit message should look like based on a description rather than an example. This patch fixes the problem by making the example concrete and imperative. The first line is a real life imperative statement with a ticket number from our issue tracker. The body describes the behavior without the patch, why this is a problem, and how the patch fixes the problem when applied.
- Make sure you have added tests for your changes. request that you weren’t able to add tests.
- Run all the tests to assure nothing else was accidentally broken.
- If possible, run the acceptance tests as well as the unit tests.
- You can always ask for help getting the tests working, or with writing tests.
- Furthermore, if you aren’t up to writing tests for your work, indicate it clearly in your pull request. You won’t be rejected for a lack of tests, but someone else will need to add those tests before we can merge your contribution.
Branch and Version Compatibility¶
Any change to a module should strive as much as possible to be compatible with all released versions of Puppet. We want to avoid multiple incompatible versions existing as much as possible.
We are willing to accept backward-incompatible changes if there is no possible way around it. Those changes MUST provide a migration strategy and, if possible, deprecation warnings about the older functionality. Ask for help from the community or a Puppet Labs employee if you’d like some advice on approaches here.
- Push your changes to a topic branch in your fork of the repository.
- Submit a pull request to the repository in the puppetlabs organization.
- Update your ticket to mark that you have submitted code and are ready to be reviewed, if it is separate from the pull request.
- Mentioning the issue number in the subject will make this happen through GitHub magic.
A committer checks that the pull request is well formed. If not, they will ask that it is fixed:
it is on it’s own, appropriately named, branch.
- it only has commits relevant to the specific issue.
it has appropriate, clear, and effective commit messages.
A committer can start a pull request specific discussion; at this point that covers:
Reviewing the code for any obvious problems.
- Providing feedback based on personal experience on the subject.
- Testing relevant examples on an untested platform.
- Thoroughly stepping through the change to understand potential side-effects.
- Examining discrepancies between the original issue and the pull request.
- Using @mentioning to involve another committer in the discussion.
Anyone can offer their assessment of a pull request, or be involved in the discussion, but keep in mind that this isn’t the time to decide if the pull request is desired or not. The only reason it should be rejected at this point is if someone skipped the earlier steps in the process and submitted code before any discussion happened.
- Every review should add any specific changes required to the pull request:
- For comments on specific code, using GitHub line comments.
- For general changes, include them in the final assessment.
- Every review should end by specifying the type of review, and a vote:
- Good to merge.
- Good to merge with minor changes (which are specified, or line comments).
- Not good to merge without major changes (which are specified).
- Any committer can merge after there is a vote of “good to merge”.
- Committers are trusted to do the right thing – you can merge your own code, but you should make sure you get appropriate independent review.
- Most changes should not merge unless a code review has been completed.
Becoming a Committer¶
Puppet Labs modules are an open project: any contributor can become a committer. Being a committer comes with great responsibility: your decisions directly shape the community, and the effectiveness, of Puppet Forge modules. You will probably invest more, and produce less, as a committer than a regular developer submitting pull requests.
As a committer your code is subject to the same review and commit restrictions as regular committers. You must exercise greater caution that most people in what you submit and include in the project.
On the other hand you have several additional responsibilities over and above those of a regular developer:
- You are responsible for reviewing code from other developers.
- You are responsible for giving constructive feedback that action can be taken on when code isn’t quite there yet
- You are responsible for ensuring that quality, tested code is committed.
- You are responsible for ensuring that code merges into the appropriate branch (if applicable).
- You are responsible for ensuring that our community is diverse, accepting, and friendly.
The best way to become a committer is to fulfill those requirements in the community, so that it is clear that approving you is just a formality.
The process for adding a committer is:
- A candidate has demonstrated familiarity with the quality guidelines and coding standards by submitting at least two pull requests that are accepted without modification.
- The candidate is proposed by an existing committer.
- The product owner at Puppet Labs responsible for the Puppet Forge and Modules reviews the candidate and makes a decision.
The decision on adding a committer is absolutely private, and any feedback to candidates about why they were not accepted is at the option of the product owner.
Removing a committer happens if they don’t live up to their responsibilities, or if they violate the community standards. This is done by the product owner. The details of why are private, and will not be shared.