[Lucene-java Wiki] Update of "HowToContribute" by SteveRowe

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Lucene-java Wiki" for change notification.

The "HowToContribute" page has been changed by SteveRowe:
http://wiki.apache.org/lucene-java/HowToContribute?action=diff&rev1=32&rev2=33

  = How to Contribute to Lucene =
+ 
+ <<TableOfContents>>
+ 
  === Getting the source code ===
- First of all, you need the Lucene source code.<<BR>>
+ First of all, you need the Lucene source code.
  
  Get the source code on your local drive using [[http://svn.apache.org/viewvc/lucene/dev/|SVN]].  Most development is done on the "trunk":
  
  {{{
  svn checkout http://svn.apache.org/repos/asf/lucene/dev/trunk/ lucene-trunk
+ }}}
  
- }}}
  Depending on where you are located the European mirror might be faster or slower:
  
  {{{
@@ -29, +32 @@

  But take care about the following points:
  
   * Code compatibility:
-   * All core code to be included in 2.X releases should be compatible with Java 1.4.
-   * All contrib code should be compatible with either Java 5 or 1.4.
    * All code to be included in 3.X releases should be compatible with Java 5.
-  * All public classes and methods should have informative [[http://java.sun.com/j2se/javadoc/writingdoccomments/|Javadoc comments]].
+   * All code to be included in trunk, from which 4.0 will be released, should be compatible with Java 6.
+  * All public classes and methods should have informative [[http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html|Javadoc comments]].
   * Code should be formatted according to [[http://java.sun.com/docs/codeconv/|Sun's conventions]] with one exception:
    * indent two spaces per level, not four.
   * Contributions should pass existing unit tests.
   * New unit tests should be provided to demonstrate bugs and fixes (http://www.junit.org).
-  * In the trunk, the java source code is in the directory src/java and the java test code is in the directory src/test.
+  * The java source code is in the directory lucene/src/java and the java test code is in the directory lucene/src/test.
  
  === 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.
+ 
  ==== Unit Tests ====
- To run your test case from ant use the following:
+ Please make sure that all unit tests succeed before constructing your patch.
+ 
+ To run your test case from ant use the following from the {{{lucene/}}} directory in your working copy:
  
  {{{
- > cd lucene-trunk/lucene
- > ant -Dtestcase=NameOfYourUnitTest test-core
+ ant -Dtestcase=NameOfYourUnitTest test-core
  }}}
+ 
  In case your contribution fixes a bug, try and make your test case fail to show the presence of the bug. A test case showing the presence of a bug is also a good contribution by itself.
  
- Once your test case passes, please make sure that all unit tests (core, contrib, back-compatibility, and Solr tests) succeed before constructing your patch, by running this from the top-level:
+ Once your test case passes, please make sure that all unit tests (core, contrib, back-compatibility, and Solr tests) succeed before constructing your patch, by running this from the {{{lucene/}}} directory in your working copy:
  
  {{{
- > cd lucene-trunk
- > ant clean test
+ ant clean test
  }}}
+ 
  After a while, if you see
  
  {{{
  BUILD SUCCESSFUL
  }}}
+ 
  all is ok, but if you see
  
  {{{
  BUILD FAILED
  }}}
+ 
  please, read carefully the errors messages and check your code.
  
  Since running all test cases can take some time, after any change try running a previously failing single test case first.
@@ -75, +83 @@

  {{{
  svn stat
  }}}
+ 
  Add any new files with:
  
  {{{
  svn add src/.../MyNewClass.java
  }}}
+ 
  Edit the ''CHANGES.txt'' file, adding a description of your change, including the bug number it fixes.
  
  In order to create a patch, just type:
  
  {{{
- svn diff > LUCENE-NNN.patch
+ svn diff > LUCENE-NNNN.patch
  }}}
- This will report all modifications done on Lucene sources on your local disk and save them into the ''LUCENE-NNN.patch'' file.  Read the patch file.   Make sure it includes ONLY the modifications required to fix a single issue.
  
- Note the ''LUCENE-NNN.patch'' patch file name.  Please use this naming pattern when creating patches for uploading to JIRA.  Once you create a new JIRA issue, note its name and use that name when naming your patch file.  For example, if you are creating a patch for a JIRA issue named LUCENE-123, then name your patch filename LUCENE-123.patch.  If you are creating a new version of an existing patch, use the existing patch's file name.  JIRA will automatically "gray out" the old patch and clearly mark your newly uploaded patch as the latest.
+ This will report all modifications done on Lucene sources on your local disk and save them into the ''LUCENE-NNNN.patch'' file.  Read the patch file.   Make sure it includes ONLY the modifications required to fix a single issue.
  
+ Note the ''LUCENE-NNNN.patch'' patch file name.  Please use this naming pattern when creating patches for uploading to JIRA.  Once you create a new JIRA issue, note its name and use that name when naming your patch file.  For example, if you are creating a patch for a JIRA issue named LUCENE-3456, then name your patch filename LUCENE-3456.patch.  If you are creating a new version of an existing patch, use the existing patch's file name.  JIRA will automatically "gray out" the old patch and clearly mark your newly uploaded patch as the latest.
+ 
- Please do not:
+ Please '''do not''':
  
   * reformat code unrelated to the bug being fixed: formatting changes should be separate patches/commits.
   * comment out code that is now obsolete: just remove it.
@@ -99, +110 @@

   * make things public which are not required by end users.
   * Add @author tags to your code.  (Instead, give yourself credit in the CHANGES.txt file.)
  
- Please do:
+ Please '''do''':
  
   * try to adhere to the coding style of files you edit;
   * comment code whose function or rationale is not obvious;
@@ -108, +119 @@

  === Contributing your work ===
  Finally, patches should be attached to a bug report in [[http://issues.apache.org/jira/browse/LUCENE|Jira]].
  
- 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.
+ 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 others' 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.
  
  == Stay involved ==
  Contributors should join the [[http://lucene.apache.org/java/docs/mailinglists.html|Lucene mailing lists]].  In particular, the commit list (to see changes as they are made), the dev list (to join discussions of changes) and the user list (to help others).
@@ -119, +130 @@

  The following resources may prove helpful when developing Lucene contributions.  (These are not an endorsement of any specific development tools)
  
   * [[http://people.apache.org/~rmuir/Eclipse-Lucene-Codestyle.xml|Eclipse Galileo codestyle.xml file for Lucene's coding conventions]]
-  * [[attachment:Intellij-Lucene-Codestyle.xml|IntelliJ IDEA codestyle.xml file for Lucene's coding conventions]]
   * Setting up the .classpath - copy the contents of [[attachment:eclipse.lucene.classpath|this]] file to your project's .classpath file. Note that you may need to change the location of ant.jar.
   * IntelliJ, Eclipse, Maven: information for both Lucene and SOLR can be found at [[http://wiki.apache.org/solr/HowToContribute#Development_Environment_Tips|SOLR How To Contribute]]
   * Additional information on [[RunningTests|running tests]].
  
+ == Getting your feet wet: where to begin? ==
+ 
+ New to Lucene?  Want to find JIRA issues that you can work on without taking on the whole world?
+ 
+ The Lucene/Solr developers use the "newdev" label to mark issues that developers new to Lucene might be interested in working on.  The rough criteria used to make this selection are:
+ 
+  * Nobody has done any work on the issue yet.
+  * The issue is likely not controversial.
+  * The issue is likely self-contained with limited scope.
+ 
+ To see a list of open Lucene and Solr issues with the newdev label, use the JIRA query [[https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&jqlQuery=%28project%3DSOLR+OR+project%3DLUCENE%29+AND+%28status%3DOPEN+OR+status%3DREOPENED%29+AND+labels%3Dnewdev|(project=SOLR OR project=LUCENE) AND (status=OPEN OR status=REOPENED) AND labels=newdev]]
+ 
+ '''Note:''' Fixing these issues may require asking questions on the developer list to figure out what they mean - there is no guarantee that any of these will be either quick or easy.
+