Differences between revisions 1 and 44 (spanning 43 versions)
Revision 1 as of 2006-05-09 05:07:32
Size: 3613
Editor: adsl-63-201-33-163
Comment: nearly verbatim copy of hadoop rev#3
Revision 44 as of 2013-04-03 16:20:12
Size: 3131
Editor: pool-96-231-149-40
Comment: try to be less verbose/overwhelming with wording and formatting
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
<<TableOfContents>>

== Working With Code ==
Line 4: Line 8:
First of all, you need the Lucene source code.
Line 5: Line 10:
First of all, you need the Lucene source code.[[BR]]

Get the source code on your local drive using [http://svn.apache.org/viewcvs.cgi/lucene/java/ SVN]. Most development is done on the "trunk":

{{{
svn checkout http://svn.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
 * 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].
 * Contributions should pass existing unit tests.
 * New unit tests should be provided to demonstrate bugs and fixes ([http://www.junit.org]).

=== Generating a patch ===

Please make sure that all unit tests succeed before constructing your patch.
Get the source code using [[http://svn.apache.org/viewvc/lucene/dev/|SVN]]: {{{svn checkout http://svn.apache.org/repos/asf/lucene/dev/trunk/ lucene-trunk}}}
Line 30: Line 13:
Please make sure that all unit tests succeed before constructing your patch: {{{ant clean test}}}
Line 31: Line 15:
{{{
> cd lucene-trunk
> 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.
To run a single test case from the {{{lucene/}}} directory in your working copy: {{{ant -Dtestcase=NameOfYourUnitTest test}}}

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.
Line 46: Line 20:
Check to see what files you have modified with:
{{{
svn stat
}}}
 1. Check to see what files you have modified with: {{{svn stat}}}
 1. Add any new files with: {{{svn add src/.../MyNewClass.java}}}
 1. In order to create a patch, just type: {{{svn diff > LUCENE-NNNN.patch}}}
Line 51: Line 24:
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 > myBeautifulPatch.patch
}}}

This will report all modifications done on Lucene sources on your local disk and save them into the ''myBeautifulPath.patch'' file. Read the patch file.
Make sure it includes ONLY the modifications required to fix a single issue.

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.
 * 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.

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.)
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.
Line 79: Line 27:
Finally, patches should be attached to a bug report in [[http://issues.apache.org/jira/browse/LUCENE|Jira]].
Line 80: Line 29:
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.
Line 85: Line 32:
Contributors should join the [[http://lucene.apache.org/core/discussion.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).
Line 86: Line 34:
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.

== 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, look at this link [[http://s.apache.org/newdevlucenesolr|http://s.apache.org/newdevlucenesolr]]

'''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.

== Developer tips ==

For more contribution guidelines and tips, see [[DeveloperTips]]

How to Contribute to Lucene

Working With Code

Getting the source code

First of all, you need the Lucene source code.

Get the source code using SVN: svn checkout http://svn.apache.org/repos/asf/lucene/dev/trunk/ lucene-trunk

Unit Tests

Please make sure that all unit tests succeed before constructing your patch: ant clean test

To run a single test case from the lucene/ directory in your working copy: ant -Dtestcase=NameOfYourUnitTest test

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.

Creating a patch

  1. Check to see what files you have modified with: svn stat

  2. Add any new files with: svn add src/.../MyNewClass.java

  3. In order to create a patch, just type: svn diff > LUCENE-NNNN.patch

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.

Contributing your work

Finally, patches should be attached to a bug report in 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 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 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.

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, look at this link http://s.apache.org/newdevlucenesolr

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.

Developer tips

For more contribution guidelines and tips, see DeveloperTips

HowToContribute (last edited 2016-07-27 14:10:18 by DavidSmiley)