ContributingCode.md

The Melange project welcomes code changes from everyone.

Contributor License Agreement

You must sign a Contributor License Agreement before we can accept your contributions.

Drafting Your Change

Please conform to 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 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 (on Google Code), the log message might say “Fixes issue 15 (on Google Code).”). 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 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. Congratuations!