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