lucene-java-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Lucene-java Wiki] Update of "HowToContribute" by Shai Erera
Date Sun, 28 Feb 2010 05:20:52 GMT
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 Shai Erera.
http://wiki.apache.org/lucene-java/HowToContribute?action=diff&rev1=16&rev2=17

--------------------------------------------------

  = How to Contribute to Lucene =
- 
  === Getting the source code ===
- 
  First of all, you need the Lucene source code.<<BR>>
  
  Get the source code on your local drive using [[http://svn.apache.org/viewvc/lucene/java/|SVN]].
 Most development is done on the "trunk":
@@ -11, +9 @@

  {{{
  svn checkout http://svn.apache.org/repos/asf/lucene/java/trunk/ lucene-trunk
  }}}
- 
  Depending on where you are located the European mirror might be faster or slower:
  
  {{{
  svn checkout http://svn.eu.apache.org/repos/asf/lucene/java/trunk/ lucene-trunk
  }}}
- 
  === Making Changes ===
- 
  Before you start, send a message to the [[http://lucene.apache.org/java/docs/mailinglists.html|developer
mailing list]] (Note: you have to subscribe before you can post), or file a bug report in
[[http://issues.apache.org/jira/browse/LUCENE|Jira]].  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 using your favorite IDE.<<BR>>
  
  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 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 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 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]].
   * 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.
+   * 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]]).
+  * 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.
  
  === Generating a patch ===
- 
  ==== Unit Tests ====
- 
  To run your test case from ant use the following:
  
  {{{
  > cd lucene-trunk
  > 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, and back-compatibility)
succeed before constructing your patch, by running this:
@@ -56, +49 @@

  > ant clean test test-tag
  }}}
  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.
- Since running all test cases can take some time,
- after any change try running a previously failing single test case first.
  
  ==== Creating a patch ====
  Check to see what files you have modified with:
+ 
  {{{
  svn stat
  }}}
+ Add any new files with:
  
- 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:
@@ -86, +80 @@

  {{{
  svn diff > LUCENE-NNN.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.  
+ 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.
- 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.
  
  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.  
+  * 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.
   * 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:
+ 
   * 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.)
  
  === 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.
  
  == 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).
  
  Please keep discussions about Lucene on list so that everyone benefits.  Emailing individual
committers with questions about specific Lucene issues is discouraged.  See http://people.apache.org/~hossman/#private_q.
  
  == Helpful Resources ==
- 
  The following resources may prove helpful when developing Lucene contributions.  (These
are not an endorsement of any specific development tools)
  
-    * [[attachment:Eclipse-Lucene-Codestyle.xml|Eclipse Galileo codestyle.xml file for Lucene's
coding conventions]]
+  * [[attachment:Eclipse-Lucene-Codestyle.xml|Eclipse Galileo codestyle.xml file for Lucene's
coding conventions]]
-    * [[http://wiki.apache.org/solr-data/attachments/HowToContribute/attachments/IntelliJ.codestyle.xml|IntelliJ
IDEA codestyle.xml file for Lucene's coding conventions]]
+  * [[http://wiki.apache.org/solr-data/attachments/HowToContribute/attachments/IntelliJ.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.
  

Mime
View raw message