blob: 715abdf1e01d74dfc2f219e1ba12e6d89ea9e053 [file] [log] [blame]
#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
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 <>"
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
[ 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
[ Melange's master branch].
_Copyright 2014 Google Inc._
_This work is licensed under a_
[ Creative Commons Attribution 2.5 License].