| #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] |