Update links for Incubator podling rather than Lucene subproject.
Kill off old HowToContribute, link to CONTRIBUTING
|Deletions are marked like this.||Additions are marked like this.|
|Line 1:||Line 1:|
|= How to Contribute to Lucy =||= Relocated =|
|Line 3:||Line 3:|
|=== Getting the source code ===
The Lucy source code is maintained within the Apache Software Foundation's Subversion repository, which you can browse at [[http://svn.apache.org/viewvc/incubator/lucy/]]. Most development is done on the "trunk":
|This page has been superseded by the document named "[[http://svn.apache.org/repos/asf/lucy/trunk/CONTRIBUTING| CONTRIBUTING]]" at the top of the Lucy source code hierarchy.|
|Line 8:||Line 6:|
|svn checkout http://svn.apache.org/repos/asf/incubator/lucy/trunk/ lucy-trunk||http://svn.apache.org/repos/asf/lucy/trunk/CONTRIBUTING|
|Line 10:||Line 8:|
Depending on where you are located the European mirror might be faster or slower:
svn checkout http://svn.eu.apache.org/repos/asf/incubator/lucy/trunk/ lucy-trunk
=== Making Changes ===
Before you start, send a message to the Lucy [[http://mail-archives.apache.org/mod_mbox/incubator-lucy-dev/| developer's mailing list]]. (Note: you have to subscribe before you can post). 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 using your favorite text editor or IDE. Please take the following points into account:
* All code will eventually need to be portable to multiple operating systems and compilers. (This is a complex requirement and it should not block your contribution.)
* All public APIs should be accompanied by informative documentation.
* Code should be formatted according to the style guidelines at LucyStyleGuide.
* Contributions should pass existing unit tests.
* New unit tests should be provided to demonstrate bugs and fixes, and to demonstrate that new features work as documented.
* Simplicity, both in terms of API and implementation, is highly valued within the Lucy development community; the simpler the contribution, the more quickly it can be reviewed and integrated.
=== Generating a patch ===
==== Unit Tests ====
In case your contribution fixes a bug, try to create a failing test case which demonstrates 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 existing unit tests succeed before constructing your patch, by running this:
> cd lucy-trunk/perl
> perl Build.PL
> ./Build test
(At the time of this writing, only the Perl bindings run the complete test suite.)
==== Creating a patch ====
Check to see what files you have modified with:
Add any new files with
svn add [...]/MyFile.c
In order to create a patch, just type:
svn diff > my_patch.diff
This will report all modifications done on Lucy sources on your local disk and save them into the ''my_patch.diff'' file. Read the patch file. Make sure it includes ONLY the modifications required to fix a single issue.
If you are creating a new version of an existing patch, use the existing patch's file name. Our issue-tracking software, 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.
* 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.
* try to adhere to the coding style of files you edit.
* comment liberally.
* update documentation to reflect your changes.
=== Contributing your work ===
Finally, contribute your patch via our issue-tracker/bug-tracker. The installation is at [[http://issues.apache.org/jira/browse/LUCY]]; it runs on [[http://www.atlassian.com/software/jira/|Atlassian JIRA]], and we generally use the term "issue" rather than "bug" because not every contribution fixes a "bug".
1. Create a JIRA account for yourself and sign in.
1. Once you have signed in, the "create new issue" link will appear. Use it to open a new Lucy JIRA issue.
1. Attach your submission to the issue using JIRA's "Attach file" feature.
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://incubator.apache.org/lucy | Lucy 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).
This page has been superseded by the document named "CONTRIBUTING" at the top of the Lucy source code hierarchy.