From: Steven Kurylo Date: Wed, 16 Apr 2014 18:06:36 +0000 (-0700) Subject: (doc) Sync latest CONTRIBUTING.md X-Git-Tag: 1.1.1~2^2~2 X-Git-Url: https://review.fuel-infra.org/gitweb?a=commitdiff_plain;h=77c433962d8683d77bc26894a097a6fef17717e6;p=puppet-modules%2Fpuppetlabs-firewall.git (doc) Sync latest CONTRIBUTING.md This is the latest CONTRIBUTING.md from https://github.com/puppetlabs/puppet/blob/master/CONTRIBUTING.md The old version has out of date links. --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f0dbf1..aa27d05 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,292 +1,87 @@ -Checklist (and a short version for the impatient) -================================================= - - * Commits: - - - Make commits of logical units. - - - Check for unnecessary whitespace with "git diff --check" before - committing. - - - Commit using Unix line endings (check the settings around "crlf" in - git-config(1)). - - - Do not check in commented out code or unneeded files. - - - The first line of the commit message should be a short - description (50 characters is the soft limit, excluding ticket - number(s)), and should skip the full stop. - - - Associated the Redmine ticket in the message. The first line - should include the ticket number in the form "(#XXXX) Rest of - message". - - - The body should provide a meaningful commit message, which: - - - uses the imperative, present tense: "change", not "changed" or - "changes". - - - includes motivation for the change, and contrasts its - implementation with the previous behavior. - - - Make sure that you have tests for the bug you are fixing, or - feature you are adding. - - - Make sure the test suite passes after your commit (rake spec unit). - - * Submission: - - * Pre-requisites: - - - Make sure you have a [Redmine account](http://projects.puppetlabs.com) - - - Sign the [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign) - - - [Create a ticket](http://projects.puppetlabs.com/projects/modules/issues/new), or [watch the ticket](http://projects.puppetlabs.com/projects/modules/issues) you are patching for. - - * Preferred method: - - - Fork the repository on GitHub. - - - Push your changes to a topic branch in your fork of the - repository. (the format ticket/1234-short_description_of_change is - usually preferred for this project). - - - Submit a pull request to the repository in the puppetlabs - organization. - -The long version -================ - - 0. Decide what to base your work on. - - In general, you should always base your work on the oldest - branch that your change is relevant to. - - - A bug fix should be based on the current stable series. If the - bug is not present in the current stable release, then base it on - `master`. - - - A new feature should be based on `master`. - - - Security fixes should be based on the current maintenance series - (that is, the previous stable series). If the security issue - was not present in the maintenance series, then it should be - based on the current stable series if it was introduced there, - or on `master` if it is not yet present in a stable release. - - 1. Make separate commits for logically separate changes. - - Please break your commits down into logically consistent units - which include new or changed tests relevent to the rest of the - change. The goal of doing this is to make the diff easier to - read for whoever is reviewing your code. In general, the easier - your diff is to read, the more likely someone will be happy to - review it and get it into the code base. - - If you're going to refactor a piece of code, please do so as a - separate commit from your feature or bug fix changes. - - We also really appreciate changes that include tests to make - sure the bug isn't re-introduced, and that the feature isn't - accidentally broken. - - Describe the technical detail of the change(s). If your - description starts to get too long, that's a good sign that you - probably need to split up your commit into more finely grained - pieces. - - Commits which plainly describe the things which help - reviewers check the patch and future developers understand the - code are much more likely to be merged in with a minimum of - bike-shedding or requested changes. Ideally, the commit message - would include information, and be in a form suitable for - inclusion in the release notes for the version of Puppet that - includes them. - - Please also check that you are not introducing any trailing - whitespaces or other "whitespace errors". You can do this by - running "git diff --check" on your changes before you commit. - - 2. Sign the Contributor License Agreement - - Before we can accept your changes, we do need a signed Puppet - Labs Contributor License Agreement (CLA). - - You can access the CLA via the - [Contributor License Agreement link](https://projects.puppetlabs.com/contributor_licenses/sign) - in the top menu bar of our Redmine instance. Once you've signed - the CLA, a badge will show up next to your name on the - [Puppet Project Overview Page](http://projects.puppetlabs.com/projects/modules?jump=welcome), - and your name will be listed under "Contributor License Signers" - section. - - If you have any questions about the CLA, please feel free to - contact Puppet Labs via email at cla-submissions@puppetlabs.com. - - 3. Sending your patches - - We accept multiple ways of submitting your changes for - inclusion. They are listed below in order of preference. - - Please keep in mind that any method that involves sending email - to the mailing list directly requires you to be subscribed to - the mailing list, and that your first post to the list will be - held in a moderation queue. - - * GitHub Pull Requests - - To submit your changes via a GitHub pull request, we _highly_ - recommend that you have them on a topic branch, instead of - directly on "master" or one of the release, or RC branches. - It makes things much easier to keep track of, especially if - you decide to work on another thing before your first change - is merged in. - - GitHub has some pretty good - [general documentation](http://help.github.com/) on using - their site. They also have documentation on - [creating pull requests](http://help.github.com/send-pull-requests/). - - In general, after pushing your topic branch up to your - repository on GitHub, you'll switch to the branch in the - GitHub UI and click "Pull Request" towards the top of the page - in order to open a pull request. - - You'll want to make sure that you have the appropriate - destination branch in the repository under the puppetlabs - organization. This should be the same branch that you based - your changes off of. - - * Other pull requests - - If you already have a publicly accessible version of the - repository hosted elsewhere, and don't wish to or cannot use - GitHub, you can submit your change by requesting that we pull - the changes from your repository by sending an email to the - puppet-dev Google Groups mailing list. - - `git-request-pull(1)` provides a handy way to generate the text - for the email requesting that we pull your changes (and does - some helpful sanity checks in the process). - - * Mailing patches to the mailing list - - If neither of the previous methods works for you, then you can - also mail the patches inline to the puppet-dev Google Group - using either `rake mail_patches`, or by using - `git-format-patch(1)`, and `git-send-email(1)` directly. - - `rake mail_patches` handles setting the appropriate flags to - `git-format-patch(1)` and `git-send-email(1)` for you, but - doesn't allow adding any commentary between the '---', and the - diffstat in the resulting email. It also requires that you - have created your topic branch in the form - `//`. - - If you decide to use `git-format-patch(1)` and - `git-send-email(1)` directly, please be sure to use the - following flags for `git-format-patch(1)`: -C -M -s -n - --subject-prefix='PATCH/puppet' - - * Attaching patches to Redmine - - As a method of last resort you can also directly attach the - output of `git-format-patch(1)`, or `git-diff(1)` to a Redmine - ticket. - - If you are generating the diff outside of Git, please be sure - to generate a unified diff. - - 4. Update the related Redmine ticket. - - If there's a Redmine ticket associated with the change you - submitted, then you should update the ticket to include the - location of your branch, and change the status to "In Topic - Branch Pending Merge", along with any other commentary you may - wish to make. - -How to track the status of your change after it's been submitted -================================================================ - -Shortly after opening a pull request on GitHub, there should be an -automatic message sent to the puppet-dev Google Groups mailing list -notifying people of this. This notification is used to let the Puppet -development community know about your requested change to give them a -chance to review, test, and comment on the change(s). - -If you submitted your change via manually sending a pull request or -mailing the patches, then we keep track of these using -[patchwork](https://patchwork.puppetlabs.com). When code is merged -into the project it is automatically removed from patchwork, and the -Redmine ticket is manually updated with the commit SHA1. In addition, -the ticket status must be updated by the person who merges the topic -branch to a status of "Merged - Pending Release" - -We do our best to comment on or merge submitted changes within a week. -However, if there hasn't been any commentary on the pull request or -mailed patches, and it hasn't been merged in after a week, then feel -free to ask for an update by replying on the mailing list to the -automatic notification or mailed patches. It probably wasn't -intentional, and probably just slipped through the cracks. - -Additional Resources -==================== - -* [Getting additional help](http://projects.puppetlabs.com/projects/puppet/wiki/Getting_Help) - -* [Writing tests](http://projects.puppetlabs.com/projects/puppet/wiki/Development_Writing_Tests) - -* [Bug tracker (Redmine)](http://projects.puppetlabs.com/projects/modules) - -* [Patchwork](https://patchwork.puppetlabs.com) - -* [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign) - +# How to contribute + +Third-party patches are essential for keeping puppet great. We simply can't +access the huge number of platforms and myriad configurations for running +puppet. We want to keep it as easy as possible to contribute changes that +get things working 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. + +## Getting Started + +* Make sure you have a [Jira account](http://tickets.puppetlabs.com) +* Make sure you have a [GitHub account](https://github.com/signup/free) +* Submit a ticket for your issue, assuming one does not already exist. + * Clearly describe the issue including steps to reproduce when it is a bug. + * Make sure you fill in the earliest version that you know has the issue. +* Fork the repository on GitHub + +## Making Changes + +* Create a topic branch from where you want to base your work. + * This is usually the master branch. + * Only target release branches if you are certain your fix must be on that + branch. + * To quickly create a topic branch based on master; `git branch + fix/master/my_contribution master` then checkout the new branch with `git + checkout fix/master/my_contribution`. Please avoid working directly on the + `master` branch. +* Make commits of logical units. +* Check for unnecessary whitespace with `git diff --check` before committing. +* Make sure your commit messages are in the proper format. + +```` + (PUP-1234) 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 the necessary tests for your changes. +* Run _all_ the tests to assure nothing else was accidentally broken. + +## Making Trivial Changes + +### Documentation + +For changes of a trivial nature to comments and documentation, it is not +always necessary to create a new ticket in Jira. In this case, it is +appropriate to start the first line of a commit with '(doc)' instead of +a ticket number. + +```` + (doc) Add documentation commit example to CONTRIBUTING + + There is no example for contributing a documentation commit + to the Puppet repository. This is a problem because the contributor + is left to assume how a commit of this nature may appear. + + The first line is a real life imperative statement with '(doc)' in + place of what would have been the ticket number in a + non-documentation related commit. The body describes the nature of + the new documentation or comments added. +```` + +## Submitting Changes + +* Sign the [Contributor License Agreement](http://links.puppetlabs.com/cla). +* 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 Jira ticket to mark that you have submitted code and are ready for it to be reviewed (Status: Ready for Merge). + * Include a link to the pull request in the ticket. + +# Additional Resources + +* [More information on contributing](http://links.puppetlabs.com/contribute-to-puppet) +* [Bug tracker (Jira)](http://tickets.puppetlabs.com) +* [Contributor License Agreement](http://links.puppetlabs.com/cla) * [General GitHub documentation](http://help.github.com/) - * [GitHub pull request documentation](http://help.github.com/send-pull-requests/) - -If you have commit access to the repository -=========================================== - -Even if you have commit access to the repository, you'll still need to -go through the process above, and have someone else review and merge -in your changes. The rule is that all changes must be reviewed by a -developer on the project (that didn't write the code) to ensure that -all changes go through a code review process. - -Having someone other than the author of the topic branch recorded as -performing the merge is the record that they performed the code -review. - - * Merging topic branches - - When merging code from a topic branch into the integration branch - (Ex: master, 2.7.x, 1.6.x, etc.), there should always be a merge - commit. You can accomplish this by always providing the `--no-ff` - flag to `git merge`. - - git merge --no-ff --log ticket/1234-fix-something-broken - - The reason for always forcing this merge commit is that it - provides a consistent way to look up what changes & commits were - in a topic branch, whether that topic branch had one, or 500 - commits. For example, if the merge commit had an abbreviated - SHA-1 of `coffeebad`, then you could use the following `git log` - invocation to show you which commits it brought in: - - git log coffeebad^1..coffeebad^2 - - The following would show you which changes were made on the topic - branch: - - git diff coffeebad^1...coffeebad^2 - - Because we _always_ merge the topic branch into the integration - branch the first parent (`^1`) of a merge commit will be the most - recent commit on the integration branch from just before we merged - in the topic, and the second parent (`^2`) will always be the most - recent commit that was made in the topic branch. This also serves - as the record of who performed the code review, as mentioned - above. +* #puppet-dev IRC channel on freenode.org