| #summary Guidelines for contributing code to Melange |
| #labels Contents-Complete,Phase-Guidelines,Importance-Useful |
| |
| The [MelangeIntro Melange project] welcomes code changes from everyone. |
| |
| == Contributor License Agreement == |
| |
| *You must [ContributorLicenseAgreements sign a Contributor License Agreement] |
| before we can accept your contributions.* |
| |
| == Drafting Your Change == |
| |
| Please conform to [PythonStyleGuide Melange's Style Guide] when making |
| your change. If your change is of sufficient complexity to warrant |
| changed or additional test coverage, please change or add tests in |
| accordance with [TestingGuidelines Melange's testing guidelines]. |
| |
| == Committing Your Change == |
| |
| Any change to Melange requiring less than a day of work should be |
| proposed in the form of one or more commits. When creating a commit, |
| please deliberately author all three aspects of the commit. |
| |
| === Commit Content === |
| |
| The number of changed files and number of changed lines in your commit |
| should be as small as possible. There should be no extraneous or |
| irrelevant changes to Melange included in your commit. `git status`, |
| `git diff`, and `git checkout` will help you create a commit |
| containing just the content changes that you intend to include. |
| |
| === Commit Metadata === |
| |
| Commit log messages should be styled in the following manner: |
| |
| {{{ |
| One line under 70 characters summarizing the change. |
| |
| After a blank line, a more detailed paragraph explaining the |
| reason for the change (not necessarily what was changed, as that can |
| be seen by readers in the patch). Please wrap your lines at 70 |
| characters. |
| |
| If necessary, additional paragraphs affording more information, |
| also wrapped at 70 characters and separated from one another by |
| single blank lines. |
| }}} |
| |
| Commit log messages should follow a "what, then if necessary, why, |
| and if further necessary, how" rule for their content: the commit |
| log message should first describe the content of the change. Then, if |
| not clear from the context of the change, the commit log message |
| should state the reason for the change (for example, if the change |
| fixes issue 15, the log message might say "Fixes issue 15."). |
| Lastly, if the means by which the change was made is not apparent |
| from the context of the change (for example, if the change was made |
| by running some tool over the entire codebase rather than by manual |
| editing of individual files), the commit log message should describe |
| how the change was made. |
| |
| Metadata outside the commit log message should identify who made the |
| change and when it was made. Author and committer fields should be |
| of the form: |
| |
| {{{ |
| "FirstName LastName <somebody@example.com>" |
| }}} |
| |
| The commit's Date and Commit Date fields should be accurate. |
| |
| === Provenance === |
| |
| Because integrating a git commit means integrating every commit from |
| which it is descended, good changes should not be made "on top of" |
| bad changes. New commits should be given |
| [http://code.google.com/p/soc/source/list?num=300 the head of Melange's master branch] |
| as their parent commit unless some particular complexity germane to |
| the change being made requires some other commit (or commits) to be |
| chosen as parent(s) of the new commit. |
| |
| == Code Reviews == |
| |
| All code incorporated into Melange's codebase must first pass code |
| review conducted by a Melange committer. |
| |
| === Requesting A Code Review === |
| |
| *Remember to check and double-check that all tests pass before asking for a code review.* Asking for review of code that does not work is considered unmannerly. |
| |
| Please push your commit to our [[Gerrit]] instance. |
| |
| A Melange committer will conduct a review of your code, typically |
| within two or three days. |
| |
| === Responding To A Code Review === |
| |
| Typically the reviewer will ask several questions during the course |
| of the review; respond to these questions in a reply message. If |
| appropriate, push a revised version of your commit for further review. |
| |
| *Contributions by first-time contributors typically go through several |
| rounds of review.* We hope you both learn from and enjoy the process. |
| |
| === After Code Review === |
| |
| After you have created a commit that is suitable for inclusion in |
| Melange, a Melange committer will commit the change to |
| [http://melange.googlesource.com/soc Melange's master branch]. |
| Congratuations! |
| |
| ---- |
| _Copyright 2014 Google Inc._ |
| _This work is licensed under a_ |
| [http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-attribution-2_5.html Creative Commons Attribution 2.5 License]. |
| [http://creativecommons.org/licenses/by/2.5/ http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-2_5-88x31.png] |