| #summary Guidelines for contributing to Melange | |
| #labels Contents-Complete,Phase-Guidelines,Importance-Useful | |
| The [MelangeIntro Melange project] has a variety of opportunities for the | |
| community to contribute, including: | |
| * [http://code.google.com/p/soc/issues/entry Filing an issue] reporting a defect or requesting a new feature | |
| * Contributing a change to Melange's code implementing new behavior | |
| 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. | |
| == CLA == | |
| <h4>All contributors must [ContributorLicenseAgreements sign the CLA] before we can accept their contributions.<h4> | |
| == Committers == | |
| Committers in the Melange community are those individuals who have been | |
| made project members or project owners in the | |
| [http://code.google.com/p/soc/ SoC project] on | |
| [http://code.google.com 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 | |
| [ContributionReviews#Patches patches]. These individuals are the | |
| "gatekeepers" of the community, helping to insure that standards such | |
| as [PythonStyleGuide programming style] and | |
| [TestingGuidelines testing] that are important to the community as a | |
| whole are adhered to by each contributor and for each contribution. | |
| <wiki:comment> | |
| Each committer will: | |
| * be a project member (or possibly project owner) at http://code.google.com/p/soc/ | |
| * be a [MailingListsGuidelines#Developer_list developer mailing list] manager (or possibly list owner) at http://groups.google.com/group/melange-soc-dev | |
| * have an account at at [http://mail.google.com/a/googleopensourceprograms.com googleopensourceprograms.com] | |
| * be able to [ContributionReviews#Using_Rietveld_for_code_reviews conduct code reviews] at http://codereviews.googleopensourceprograms.com/ | |
| * have `ACCESS` template `VOP` (`AUTOVOICE`) in the [IrcChannelGuidelines `#melange` IRC channel] | |
| </wiki:comment> | |
| === Casual contributors === | |
| Casual developers can contribute to the [MelangeIntro Melange project] | |
| primarily through the [ContributionReviews#Patches patch process] | |
| described below. Casual contributors still need to agree to the | |
| [ContributionTerms guidelines for contributors] before their patch | |
| can be accepted and commmitted by a | |
| [ContributionReviews#Committer committer]. | |
| == Code reviews == | |
| 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 | |
| [ContributionReviews#Suggested_patches_from_casual_contributors patches] and | |
| [ContributionReviews#Reviews_after_committed_patches 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. | |
| === Code changes should be atomic === | |
| The commit of a source code change should result in a source repository | |
| where the software [BuildingMelange builds] and passes any existing | |
| [TestingGuidelines 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. | |
| === Patches === | |
| 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. | |
| === Patchfiles === | |
| 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 | |
| [MailingListsGuidelines#Developer_list 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: | |
| {{{ | |
| git diff --no-prefix > your-patch-name.patch | |
| }}} | |
| The reviewer can then apply the patch using something like: | |
| {{{ | |
| patch -p0 < your-patch-name.patch | |
| }}} | |
| ==== Patch emails ==== | |
| 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. | |
| <wiki: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: | |
| * attach a patch to an [http://code.google.com/p/soc/issues/list issue in the issue tracker] | |
| * mailing a patch to the [MailingListsGuidelines#Developer_list developer mailing list] (membership in the list is required to post to it; see the [MailingListsGuidelines#Developer_list list guidelines]) | |
| 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. | |
| </wiki:comment> | |
| ==== Code Review ==== | |
| Code review happens in the [Gerrit] system. | |
| All patches need a +2 from a Comitter before they can be submitted. | |
| <wiki: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. | |
| </wiki:comment> | |
| === Committing === | |
| 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 [ContributionReviews#Committers committer] | |
| (who may or | |
| [ContributionReviews#Suggested_patches_from_casual_contributors may | |
| not] be the actual contributor), the submit button in [Gerrit] or `git | |
| merge && git push` can be used to commit the change into the | |
| [http://code.google.com/p/soc/source/browse SoC project repository]. | |
| ==== commit messages ==== | |
| Committers should use the template below for `git commit` log messages: | |
| {{{ | |
| One line, under 68 characters giving a short description of the change | |
| After a blank line, a more detailed log message explaining the reason | |
| of the change (not necessarily what was changed, as that can be seen | |
| by readin the patch). Please wrap your lines at 70 characters again. | |
| }}} | |
| If committing contributor patch (outside of Gerrit) please include: | |
| {{{ | |
| Reviewed by: Rick Reviewer | |
| }}} | |
| 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: | |
| {{{ | |
| git commit -u "FirstName LastName <somebody@example.com>" | |
| }}} | |
| 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. | |
| == Documentation == | |
| 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. | |
| ---- | |
| _Copyright 2008 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] |