You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mahout.apache.org by ap...@apache.org on 2014/07/03 22:26:54 UTC
svn commit: r1607741 -
/mahout/site/mahout_cms/trunk/content/developers/how-to-contribute.mdtext
Author: apalumbo
Date: Thu Jul 3 20:26:54 2014
New Revision: 1607741
URL: http://svn.apache.org/r1607741
Log:
MAHOUT-1587: Update website to reflect move to GitHub
Modified:
mahout/site/mahout_cms/trunk/content/developers/how-to-contribute.mdtext
Modified: mahout/site/mahout_cms/trunk/content/developers/how-to-contribute.mdtext
URL: http://svn.apache.org/viewvc/mahout/site/mahout_cms/trunk/content/developers/how-to-contribute.mdtext?rev=1607741&r1=1607740&r2=1607741&view=diff
==============================================================================
--- mahout/site/mahout_cms/trunk/content/developers/how-to-contribute.mdtext (original)
+++ mahout/site/mahout_cms/trunk/content/developers/how-to-contribute.mdtext Thu Jul 3 20:26:54 2014
@@ -71,7 +71,7 @@ and possibly improve it.
<a name="HowToContribute-Gettingthesourcecode"></a>
## Getting the source code
-First of all, you need to get the [Mahout source code](/developers/version-control.html). Most development is done on the "trunk".
+First of all, you need to get the [Mahout source code](/developers/version-control.html). Most development is done on the "trunk". Mahout mirrors its codebase on [GitHub](https://github.com/apache/mahout). The first step to making a contribution is to fork Mahout's master branch to your GitHub repository.
<a name="HowToContribute-MakingChanges"></a>
@@ -81,58 +81,44 @@ Before you start, you should send a mess
(note: you have to subscribe before you can post), or file a ticket in our [issue tracker](/developers/issue-tracker.html).
Describe your proposed changes and check that they fit in with what others are doing and have planned for the project. Be patient, it may take folks a while to understand your requirements.
-Modify the source code and add some (very) nice features.
+ 1. Create a JIRA Issue (if one does not already exist or you haven't already)
+ 2. Pull the code from your GitHub repository
+ 3. Ensure that you are working with the latest code from the [apache/mahout](https://github.com/apache/mahout) master branch.
+ 3. Modify the source code and add some (very) nice features.
+ - Be sure to adhere to the following points:
+ - All public classes and methods should have informative Javadoc
+ comments.
+ - Code should be formatted according to the official
+ [conventions](http://www.oracle.com/technetwork/java/codeconventions-150003.pdf),
+ with two exceptions:
+ - indent two spaces per level, not four.
+ - lines can be 120 characters, not 80.
+ - Contributions should pass existing unit tests.
+ - New unit tests should be provided to demonstrate bugs and fixes.
+ 4. Commit the changes to your local repository.
+ 4. Push the code back up to your GitHub repository.
+ 5. Create a [Pull Request](https://help.github.com/articles/creating-a-pull-request) to the to apache/mahout repository on Github.
+ - Include the corresponding JIRA Issue number and description in the title of the pull request:
+ - ie. MAHOUT-xxxx: < JIRA-Issue-Description >
+ 6. Committers and other members of the Mahout community can then comment on the Pull Request. Be sure to watch for comments, respond and make any necessary changes.
-But take care about the following points
-
- * All public classes and methods should have informative Javadoc comments.
- * Code should be formatted according to the official [](http://www.oracle.com/technetwork/java/codeconventions-150003.pdf), with two exceptions:
- * indent two spaces per level, not four
- * lines can be 120 characters, not 80
- * Contributions should pass existing unit tests.
- * New unit tests should be provided to demonstrate bugs and fixes
-
-<a name="HowToContribute-Generatingapatch"></a>
-### Generating a patch
-
-A "patch file" is the format that all good contributions come in. It
-bundles up everything that is being added, removed, or changed in your
-contribution.
+Please be patient. Committers are busy people too. If no one responds to your Pull Request after a few days, please make friendly reminders. Please
+incorporate other's suggestions into into your changes if you think they're reasonable. Finally, remember that even changes that are not committed are useful to the community.
<a name="HowToContribute-UnitTests"></a>
#### Unit Tests
-Please make sure that all unit tests succeed before constructing your
-patch.
+Please make sure that all unit tests succeed before creating your pull request.
Run *mvn clean test*, if you see *BUILD SUCCESSFUL* after the tests have finished, all is ok, but if you see *BUILD FAILED*,
please carefully read the errors messages and check your code.
-<a name="HowToContribute-Creatingthepatchfile"></a>
-#### Creating the patch file
-
-Check to see what files you have modified with *svn st*, add new files with *svn add src/.../MyNewClass.java*
-
-Subversions "add" command only modifies your local copy, so it does not
-require commit permissions. By using "svn add", your entire contribution
-can be included in a single patch file, without needing to submit a
-seperate set of "new" files.
-
-Edit the ''CHANGELOG.txt'' file, adding a description of your change,
-including the bug number it fixes. In order to create a patch, just type:
-
-*svn diff > MAHOUT-$issuenumber.patch*
-
-*$issuenumber* here should be the number of the JIRA issue the patch is
-supposed to fix. This will report all modifications done on Mahout sources
-on your local disk and save them into the ''MAHOUT-$issuenumber.patch''
-file. Read the patch file. Make sure it includes ONLY the modifications
-required to fix a single issue.
+#### Do's and Don'ts
Please do not:
* reformat code unrelated to the bug being fixed: formatting changes should
-be separate patches/commits.
+be done in separate issues.
* comment out code that is now obsolete: just remove it.
* insert comments around each change, marking the change: folks can use
subversion to figure out what's changed and by whom.
@@ -142,30 +128,15 @@ Please do:
* try to adhere to the coding style of files you edit;
* comment code whose function or rationale is not obvious;
-* update documentation (e.g., ''package.html'' files, this wiki, etc.)
-
-<a name="HowToContribute-Contributingyourwork"></a>
-#### Contributing your work
-
-Finally, patches should be attached to a ticket in our [issue tracker](/developers/issue-tracker.html). If you are revising an existing patch, please re-use the exact same name
-as the previous attachment, Jira will "grey out" the older versions so it's clear which version is the newest.
-
-Please be patient. Committers are busy people too. If no one responds to your patch after a few days, please make friendly reminders. Please
-incorporate other's suggestions into into your patch if you think they're reasonable. Finally, remember that even a patch that is not committed is useful to the community.
+* update documentation (e.g., ''package.html'' files, the website, etc.)
<a name="HowToContribute-Review/ImproveExistingPatches"></a>
-## Review/Improve Existing Patches
-
-If there's a Jira issue that already has a patch you think is really good, and works well for you -- please add a comment saying so. If there's room
-for improvement (more tests, better javadocs, etc...) then make the changes and attach it as well. If a lot of people review a patch and give it a
-thumbs up, that's a good sign for committers when deciding if it's worth spending time on the patch -- and if other people have already put in
-effort to improve the docs/tests for a patch, that helps even more.
-
-<a name="HowToContribute-Applyingapatch"></a>
-## Applying a patch
-
-From the base directory (assuming that is where the patch is generated from), run:
+## Review/Improve Existing Pull Requests
-*patch [--dry-run] -p0 -i <PATH TO PATCH> *
+If there's a JIRA issue that already has a Pull Request with changes that you think are really good, and works well for you -- please add a comment saying so. If there's room
+for improvement (more tests, better javadocs, etc...) then make the changes and add a comment about them. If a lot of people review a Pull Request and give it a
+thumbs up, that's a good sign for committers when deciding if it's worth spending time to review it -- and if other people have already put in
+effort to improve the docs/tests for an issue, that helps even more.
+For more information see [Handling GitHub PRs](http://mahout.apache.org/developers/github.html).