| #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: | |
| * Creating a http://tinyurl.com/new-issue if a bug is found | |
| * Fixing bugs that annoy them | |
| 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 == | |
| 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. | |
| 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] | |
| === 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). These can either | |
| be in the form of actual output from the `diff` command, or they can be | |
| the contents of the commit log message sent to the | |
| [MailingListsGuidelines#Developer_list developer mailing list] when a | |
| [ContributionReviews#Committers committer] commits a change using `hg`. | |
| Patches should be presented for review in the "unified `diff`" format, | |
| which is the output resulting from the `svn diff` command for Subversion (the same format | |
| as that produced by `diff -uNr`) or `hg diff` command for Mercurial. This is also the same format as the diff contained in the commit log messages emailed to the developer mailing list. | |
| One special note about creating patches: please create the patch from | |
| the main directory (or the `/wiki/` directory if it is a documentation | |
| change, please note that `/wiki' directory is still on SVN repository), so that the reviewers and potential committers can apply the | |
| patch from the base of their main working copy. For example, for | |
| a checkout of `http://soc.googlecode.com/hg/` to `~/code/melange`, | |
| create the code review patch with something like: | |
| using SVN: | |
| {{{ | |
| cd ~/code/melange | |
| svn diff soc/models/new_model.py soc/views/deleted_model.py > my_change.diff | |
| }}} | |
| using Mercurial: | |
| {{{ | |
| cd ~/code/melange | |
| hg diff soc/models/new_model.py soc/views/deleted_model.py > my_change.diff | |
| }}} | |
| or changes between two revisions | |
| {{{ | |
| hg diff -r REV1 -r REV2 > my_change.diff | |
| }}} | |
| Using git (assuming origin/master is current upstream and that the desired changes have been committed): | |
| {{{ | |
| cd ~/code/melange | |
| git format-patch --no-color --no-prefix --no-numbered origin/master.. | |
| }}} | |
| In this example, `new_model.py` would be a newly-added module, and | |
| `deleted_model.py` would be a just-deleted module. The reviewer can | |
| then apply the patch using something like: | |
| {{{ | |
| cd ~/code/melange | |
| patch -p0 < my_change.diff | |
| }}} | |
| Or, if using git: | |
| {{{ | |
| cd ~/code/melange | |
| git apply --whitespace=fix -p0 my_change.diff | |
| }}} | |
| The same root directory approach should be used with | |
| [http://codereviews.googleopensourceprograms.com/static/upload.py `upload.py`] | |
| to submit | |
| [ContributionReviews#Using_Rietveld_for_code_reviews Rietveld code reviews]. | |
| ==== 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 | |
| something like: | |
| using SVN: | |
| {{{ | |
| svn diff some_module.py > some_module.diff | |
| }}} | |
| using Mercurial: | |
| {{{ | |
| hg diff some_module.py > some_module.diff | |
| }}} | |
| Or, if using git: | |
| {{{ | |
| git format-patch --no-color origin/master.. | |
| }}} | |
| For multiple files changed in the same patch, use something like: | |
| using SVN: | |
| {{{ | |
| svn diff some_module.py some_other_module.py > my_new_feature.diff | |
| }}} | |
| and Mercurial: | |
| {{{ | |
| hg diff some_module.py some_other_module.py > my_new_feature.diff | |
| }}} | |
| If using git just commit the changes and use format-patch to generate the diff. | |
| If using Mercurial and you have already committed your changes locally you can command below to create a patch of changes between two revisions: | |
| {{{ | |
| hg diff -r REV1 -r REV2 > my_change.diff | |
| }}} | |
| Alternately, committers can use `upload.py` to submit | |
| [ContributionReviews#Using_Rietveld_for_code_reviews Rietveld code reviews]. | |
| ==== Using Rietveld for code reviews ==== | |
| An instance of | |
| [http://code.google.com/p/rietveld/ Guido van Rossum's Rietveld] | |
| code review tool has been set up at | |
| http://codereviews.googleopensourceprograms.com for use by | |
| [ContributionReviews#Committers Melange committers]. An account on | |
| [http://mail.google.com/a/googleopensourceprograms.com googleopensourceprograms.com] | |
| is required in order to post code review requests and to provide code | |
| review comments. | |
| Patches supplied via the Rietveld web form should be created following | |
| [ContributionReviews#Patches these instructions]. The melange repository | |
| includes a custom version of the Rietveld `upload.py`. To start a code review, | |
| do something like this and respond to the prompts: | |
| {{{ | |
| cd ~/code/melange | |
| ./thirdparty/rietveld/upload.py \ | |
| -- soc/models/new_model.py soc/models_deleted_model.py | |
| }}} | |
| Or, if using git: | |
| {{{ | |
| cd ~/code/melange | |
| ./thirdparty/rietveld/upload.py origin/master | |
| }}} | |
| To upload an updated diff for an existing code review in progress, simply | |
| supply the extra `--issue=<the existing issue number>` option. Rietveld | |
| will then display the deltas between the previously supplied diff and the | |
| new one. | |
| ==== Using gcl to manage change sets (*Depracated since we switched to Mercurial repository and gcl supports only SVN)*==== | |
| Another useful tool for collecting multiple changes into a single "change | |
| set" for review is `gcl.py`. A copy of `gcl.py` that has been customized | |
| to upload change sets to | |
| [http://codereviews.googleopensourceprograms.com the Melange instance of Rietveld] | |
| can be found in `thirdparty/chromium/gcl.py`. `gcl.py` has quite a few features, | |
| but to get started creating a change set: | |
| {{{ | |
| cd ~/svn/soc | |
| ./thirdparty/chromium/gcl.py change some_change_set_name | |
| }}} | |
| where `some_change_set_name` is the mnemonic name of the change set you are | |
| creating. This will open an editor where you can modify the change set | |
| description. The editor will contain something like: | |
| {{{ | |
| ---All lines above this line become the description. | |
| ---Repository Root: /home/joe/svn/soc | |
| ---Paths in this changelist (some_change_set_name): | |
| ---Paths modified but not in any changelist: | |
| M trunk/app/soc/models/document.py | |
| A trunk/app/soc/logic/user | |
| M trunk/app/index.yaml | |
| }}} | |
| which you then modify something like: | |
| {{{ | |
| Add Foo feature to document.py. | |
| Patch by: Joe User | |
| ---All lines above this line become the description. | |
| ---Repository Root: /home/joe/svn/soc | |
| ---Paths in this changelist (some_change_set_name): | |
| M trunk/app/soc/models/document.py | |
| ---Paths modified but not in any changelist: | |
| A trunk/app/soc/logic/user | |
| M trunk/app/index.yaml | |
| }}} | |
| The "description" will become the `svn` log message, so be sure | |
| to follow the | |
| [ContributionReviews#svn_commit_messages message format] | |
| in this "description" portion of the change set. By the way, you can | |
| omit this part of the log message format from your "description": | |
| {{{ | |
| Review issue: N | |
| Review URL: http://codereviews.googleopensourceprograms.com/N | |
| }}} | |
| since `gcl.py` will add the "Review URL" for you when you commit | |
| (which is very convenient). | |
| The `gcl.py upload` command is used to upload the change set to | |
| [http://codereviews.googleopensourceprograms.com the Melange instance of Rietveld] | |
| for code review. See `gcl.py help` for a complete command list | |
| and additional details. | |
| ==== 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. | |
| ==== 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. | |
| === Other code review possibilities === | |
| In the future, tools like | |
| [http://code.google.com/p/gvn/ Gvn Versions Nicely] might be used for | |
| "review then commit" code reviews that make use of a "change branch" model. | |
| === 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), `hg commit` 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 `hg commit` log messages: | |
| {{{ | |
| One line, under 60-80 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 60-80 characters again. | |
| }}} | |
| Optionally if committing contributor patch 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 recently we have switched to Mercurial and now we are committing patch from contributors as if they would have commit access using command: | |
| {{{ | |
| hg 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 Mercurial repository history will indicate contributor as committer. | |
| === Branches === | |
| Previously branches were used for releases only, due to the unfriendly merge nature of svn we didn't use branches for "long term development". However since we switched to Mercurial repository we can now use branches more extensively. | |
| == 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'. Anyone 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] |