Differences between revisions 43 and 46 (spanning 3 versions)
Revision 43 as of 2013-04-03 16:06:23
Size: 3815
Editor: pool-96-231-149-40
Comment: factor this out to developertips
Revision 46 as of 2016-07-27 14:10:18
Size: 3722
Editor: DavidSmiley
Comment: Instructions on 'git diff' for feature branch
Deletions are marked like this. Additions are marked like this.
Line 10: Line 10:
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
}}}

=== 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.
Get the source code using: {{{git clone https://github.com/apache/lucene-solr/}}}
Line 20: Line 13:
Please make sure that all unit tests succeed before constructing your patch. Please make sure that all unit tests succeed before constructing your patch: {{{ant clean test}}}
Line 22: Line 15:
To run your test case from ant use the following from the {{{lucene/}}} directory in your working copy: To run a single test case from the {{{lucene/}}} directory in your working copy: {{{ant -Dtestcase=NameOfYourUnitTest test}}}
Line 24: Line 17:
{{{
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.

Once your test case passes, please make sure that all unit tests succeed before constructing your patch, by running this from your working copy:

{{{
ant clean test
}}}

Since running all test cases can take some time, after any change try running a previously failing single test case first.
In case your contribution fixes a bug, please create a new test case that fails before your fix, to show the presence of the bug and ensure it never re-occurs. A test case showing the presence of a bug is also a good contribution by itself.
Line 39: Line 20:
Check to see what files you have modified with:
Line 41: Line 21:
{{{
svn stat
}}}
Before creating your patch, you may want to get 'master' up to date with the latest from upstream. This will help avoid the possibility of others finding merge conflicts when applying your patch. This can be done with {{{git pull}}} if master is the current branch.
Line 45: Line 23:
Add any new files with: If your changes are in your git working tree (i.e. not committed to a branch), then do this:
Line 47: Line 25:
{{{
svn add src/.../MyNewClass.java
}}}
 1. Check to see what files you have modified with: {{{git status}}}
 1. Add any new files with: {{{git add src/.../MyNewClass.java}}}
 1. In order to create a patch, just type {{{git diff HEAD > LUCENE-NNNN.patch}}}.
Line 51: Line 29:
Edit the ''CHANGES.txt'' file, adding a description of your change, including the bug number it fixes. If your changes are all committed to the current (feature) branch:
Line 53: Line 31:
In order to create a patch, just type:  1. {{{git diff master... > LUCENE-NNNN.patch}}}
Line 55: Line 33:
{{{
svn diff > LUCENE-NNNN.patch
}}}
If some of your changes are committed to the current (feature) branch but you have working-copy changes too:
Line 59: Line 35:
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.  1. {{{git diff `git merge-base master head` > LUCENE-NNNN.patch}}}

This will save a diff into the ''LUCENE-NNNN.patch
'' file. Read the patch file. Make sure it includes ONLY the modifications required to fix a single issue.

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: git clone https://github.com/apache/lucene-solr/

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, please create a new test case that fails before your fix, to show the presence of the bug and ensure it never re-occurs. A test case showing the presence of a bug is also a good contribution by itself.

Creating a patch

Before creating your patch, you may want to get 'master' up to date with the latest from upstream. This will help avoid the possibility of others finding merge conflicts when applying your patch. This can be done with git pull if master is the current branch.

If your changes are in your git working tree (i.e. not committed to a branch), then do this:

  1. Check to see what files you have modified with: git status

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

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

If your changes are all committed to the current (feature) branch:

  1. git diff master... > LUCENE-NNNN.patch

If some of your changes are committed to the current (feature) branch but you have working-copy changes too:

  1. git diff `git merge-base master head` > LUCENE-NNNN.patch

This will save a diff 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)