Contributing to Puppet modules

Contribute to Puppet modules to help add new functionality, fix bugs, or make other improvements.

Your contributions help us serve a greater spectrum of platforms, hardware, software, and deployment configurations. We appreciate all kinds of user contributions, including:

  • Bug reports.

  • Feature requests.

  • Participation in our community discussion group or chat.

  • Code changes, such as bug fixes or new functionality.

  • Documentation changes, such as corrections or new usage examples.

  • Reviewing pull requests.

To make bug reports or feature requests, create a JIRA ticket in the Puppet MODULES project. If you are requesting a feature, describe the use case for it and the goal of the feature. If you are filing a bug report, clearly describe the problem and the steps to reproduce it.

Participating in community discussions is a great way to get involved. Join the community conversations in the puppet-users discussion group or our community Slack chat:

We ask everyone participating in Puppet communities to abide by our code of conduct. See our community guidelines page for details.

Contributing changes to module repositories

To contribute bug fixes, new features, expanded functionality, or documentation to Puppet modules, submit a pull request to our module repositories on GitHub.

When working on Puppet modules, follow this basic workflow:

  1. Discuss your change with the Puppet community.

  2. Fork the repository on GitHub.

  3. Make changes on a topic branch of your fork, documenting and testing your changes.

  4. Submit changes as a pull request to the Puppet repository.

  5. Respond to any questions or feedback on your pull request.

Before submitting a pull request

Discussing your change with the community

We love when people submit code changes to our projects, and we appreciate bug and typo fixes as much as we appreciate major features.

If you are proposing a significant or complex change to a Puppet module, we encourage you to discuss potential changes and their impact with the Puppet community.

To propose and discuss a change, send a message to the puppet-users discussion group or bring it up in the Puppet Community Slack #forge-modules channel.

Forking the repository and creating a topic branch

Fork the repository you want to make changes to, and create a topic branch for your work.

Give your topic branch a name that describes the work you're contributing. Always base the topic branch on the repository's primary server branch, unless one of our module developers specifically asks you to base it on a different branch.

Remember: Never work directly on the primary server branch or any other core branch.

Making changes

When you make changes to a Puppet module, make changes that are compatible with all currently supported versions of Puppet. Do not break users' existing installations or configurations with your changes. For a list of supported versions, see the Puppet component version page.

To add new classes, defined types, or tasks to a module, use Puppet Development Kit (PDK). PDK creates manifests and test templates, validates, and runs unit tests on your changes.

If you make a backward-incompatible change, you must include a deprecation warning for the old functionality, as well as documentation that tells users how to migrate to the new functionality. If you aren't sure how to proceed, ask for help in the puppet-users group or the community Slack chat.

Documenting changes

When you add documentation to modules, follow our documentation style and formatting guidelines. These guidelines help make our docs clear and easier to translate into other languages.

If you make code changes to modules, you must document your changes. We can't merge undocumented changes.

To provide usage examples, add them to the README's usage section. Include information about what the user can accomplish with each usage example.

Add reference information, such as class descriptions and parameters, as Puppet Strings-compatible code comments, so that we can generate complete documentation before we release the new version of the module. Do not manually edit generated REFERENCE.md files; any changes you make are overwritten when we generate a new file. For complete information about writing good module documentation, see Documenting modules.

In Puppet module documentation, adhere to the following conventions:

  • Lowercase module names, such as apache. This helps differentiate the module from the software the module is managing. When talking about the software being managed, capitalize names as they would normally be capitalized, such as Apache.

  • Set string values in single quotes, to make it clear that they are strings. For example, 'string' or 'C:/user/documents/example.txt'.

  • Set the values true, false, and undef in backticks, such as `true`.

  • Set data types in backticks, such as `Boolean`.

  • Set filenames, settings, directories, classes, types, defined types, functions, and similar code elements in backticks, unless the user passes them as a string value. If the user passes the value as a string, use quotes to make that clear.

  • Do not use any special marking for integer values, such as 1024.

  • Use empty lines between new lines to help with readability.

Testing your changes

Before you submit a pull request, make sure that you have added tests for your changes.

If you create new classes or defined types, PDK creates basic tests templates for you. Use PDK to validate and run unit tests on the module, to ensure that your changes don't accidentally break anything.

If you need further help writing tests or getting tests to work, ask for help in the puppet-user discussion group, in our community Slack chat, or if you created a JIRA ticket regarding your change, in the ticket.

If you don't know how to write tests for your changes, clearly say so in your pull request. We don't necessarily reject pull requests without tests, but someone needs to add the tests before we can merge your contribution.

Committing your changes

As you add code, commit your work for one function at a time. Ensure the code for each commit does only one thing. This makes it easier to remove one commit and accept another, if necessary. We would rather see too many commits than too few.

In your commit message, provide:

  1. A brief description of the behavior before your changes.

  2. Why that behavior was a problem.

  3. How your changes fix the problem.

For example, this commit message is for adding to the CONTRIBUTING document:

Make the example in CONTRIBUTING concrete
               
Without this patch applied, there is no example commit message in the CONTRIBUTING document. The contributor is left to imagine what the commit message should look. This patch adds a more specific example.

Submitting changes

Submit your changes as a pull request to the puppetlabs organization repository on GitHub.

Push your changes to the topic branch in your fork of the repository. Submit a pull request to the puppetlabs repository for the module.

Someone with the permissions to merge and commit to the Puppet repository (a committer) checks whether the pull request meets the following requirements:
  • It is on its own correctly named branch.

  • It contains only commits relevant to the specific issue.

  • It has clear commit messages that describe the problem and the solution.

  • It is appropriately and clearly documented.

Responding to feedback

Be sure to respond to any questions or feedback you receive from the Puppet modules team on your pull request. Puppet community members might also make comments or suggestions that you want to consider.

When making changes to your pull request, push your commits to the same topic branch you used for your pull request. When you push changes to the branch, it automatically updates your pull request. After the team has approved your request, someone from the modules team merges it, and your changes are included in the next release of the module.

If you do not respond to the modules team's requests, your pull request might be rejected or closed. To address such comments or questions later, create a new pull request.

Reviewing community pull requests

As a Puppet community member, you can offer feedback on someone else's contributed code.

When reviewing pull requests, any of the following contributions are helpful:

  • Review the code for any obvious problems.

  • Provide feedback based on personal experience on the subject.

  • Test relevant examples on an untested platform.

  • Look at potential side effects of the change.

  • Examine discrepancies between the original issue and the pull request.

Add your comments and questions to the pull request, pointing out any specific lines that need attention. Be sure to respond to any questions the contributor has about your comments.