The Melange project has a variety of opportunities for the community to contribute, including:
Each of these contributions is subject to review by other members of the Melange community. The guidelines for the review of various types of contributions are described here.
Committers in the Melange community are those individuals who have been
made project members or project owners in the
SoC project on
Google Code. These individuals have been given
commit privileges as a result of their previous contributions to the
Melange community, usually in the form of
patches. These individuals are the
“gatekeepers” of the community, helping to insure that standards such
as programming style and
testing that are important to the community as a
whole are adhered to by each contributor and for each contribution.
<a href='Hidden comment: Each committer will:
#melange IRC channel] '>Casual developers can contribute to the Melange project primarily through the patch process described below. Casual contributors still need to agree to the
guidelines for contributors before their patch
can be accepted and commmitted by a
committer.
Code reviews are handled in a variety of ways, depending on the size of
the change and the role of the contributor in the Melange community. Most
contributions will be in the form of small
patches and
commits. Larger
contributions, such as entire new features, probably require a different
approach, such as incremental patches and communication with the other
developers. These have similar review approaches, but tailored to the
specific situation.
The commit of a source code change should result in a source repository
where the software builds and passes any existing
tests. So, all related changes need to be committed
in such a way that each patch passes the test suite. That usually means
that new functionality is introduced in one patch, ‘enabled’ in another one,
and the old functionality removed in a third one.
The term “patches” is used to refer to relatively small changes to the
code (and, yes, this definition is intentionally vague).
Patches should be sent for review via our Gerrit instance.
It is prefered that all Patches be sent via Gerrit, but if you need to
create a traditional Patchfile, you can follow these instructions:
Usually these
are in the form of output from the git diff command.
Patches should be sent for review to the
developer mailing list and
presented in the “unified diff” format, which is de-facto standard
for many tools and the output from the git diff command (the same
format as that produced by diff -uNr). Using Git:
The reviewer can then apply the patch using something like:
Patch emails sent to the developer mailing list should begin with
[PATCH] as the first text in the email subject line, followed by a
brief (one line) description of the change.
For “small” patches (for some definition of “small”, please use good
judgment), include the diff in the email body, to facilitate inline
commenting in the code review email thread. For all patches, including
both “small” and “non small” ones, include the diff itself as an email
attachment, to make it easier for reviewers to patch the change into a
working copy with patch. Such a diff attachment can be produced with
the methods described above.
<a href='Hidden comment: ==== Suggested patches from casual contributors ====
The Melange community is interested in patches and other contributions from casual developers. To that end, casual developers can submit patches for review in a couple of ways:
Committers can then discuss the contribution with the author on the [MailingListsGuidelines#Developer_list developer mailing list], or on the [MailingListsGuidelines#General_discussion_list general discussion list] if the contributor is not on the developer list. Since the [MelangeIntro Melange project] and the [SoCOverview SoC framework] is mostly about code, there are likely to be at least a few code discussions on the general announcement list. Serious discussions will likely result in the casual contributor being invited to the developer list to move the discussion there.
Once the patch is accepted, a committer will patch a working copy and commit the changed (or added or deleted) source files to the repository, supplying a suitable commit log message. '>
Code review happens in the Gerrit system.
All patches need a +2 from a Comitter before they can be submitted.
<a href='Hidden comment: ==== Reviews after committed patches ====
Contributors with [ContributionReviews#Committers commit access] can submit changes prior to review. The participants on the [MailingListsGuidelines#Developer_list developer mailing list] are then encouraged to review the change, which will be present in the commit email that was sent to the mailing list. At least one other person with commit access should acknowledge the change with a brief “looks good to me” (LGTM) message in response (sent back to the list). This does of course not prevent other list participants from being able to make suggestions, request changes, etc.
If one or more of the list participants requests changes to the submitted code, they can either discuss it and have the original committer submit a subsequent change, or the they can make the change themselves. Please avoid conflict by trying to reach a consensus before making commits. One way to do this is to [ContributionReviews#Patches follow the patch contribution method] for reviewing a change on the developer mailing list, even if the contributor has commit access.
===== Review after commit using Google Code code reviews =====
Google Code now has a feature that enables [http://code.google.com/p/support/wiki/CodeReviews code reviews of committed code]. This feature can also be used by project owners and members to do review-after-commit style code reviews.
'>
Once all of the
[TestingGuidelines#All_changes_should_pass_smoke_tests_before_review
pre-commit tests] pass and the [ContributionReviews#Patches patch
has been code-reviewed] a committer (who may or
[ContributionReviews#Suggested_patches_from_casual_contributors may
not] be the actual contributor), the submit button in Gerrit or git<br> merge && git push can be used to commit the change into the
SoC project repository.
Committers should use the template below for git commit log messages:
If committing contributor patch (outside of Gerrit) please include:
Note that previously the person listed with “Patch by:” was the
contributor (that is, author) of the patch, however we have switched
to Git and now we are committing patch from contributors as if
they would have commit access using command:
Patches from
[ContributionReviews#Suggested_patches_from_casual_contributors casual
contributors] will, by definition, need to be committed by someone
other than the author but Git repository history will indicate
contributor as committer.
Code files should include enough internal documentation in the form of
doc strings, comments and functions with self-explanatory names
(see PythonStyleGuide) that the automatic documentation suffices.
This is the recommended way to ensure that code documentation and the
code itself stay in step.
The wiki is in the transition zone between dialog (IRC and mailing
lists) and formally reviewed content (code and its comments). Changes
to the wiki are ‘review after commit’. Any committer can log comments
for a wiki page and participate in review. At the moment rights to
create pages and edit pages directly are restricted to committers and
regular contributors to documentation.