CONTRIBUTING

===========================
Contributing to Apache Lucy
===========================

MAKE A PLAN:

  If you're looking for something to work on, see the STATUS file for a list
  of development priorities that the Lucy community has already built
  consensus around.

  If you propose to make non-trivial changes to Lucy, especially changes to
  the public API, send a note to the Lucy developer's list describing your
  plans:

    http://lucy.apache.org/mailing_lists.html
  
GET THE CODE:

  Lucy's codebase is available via Git from git-wip-us.apache.org.  Start by
  creating a clone of the repository:

    git clone https://git-wip-us.apache.org/repos/asf/lucy.git

  There is also a mirror on Github.

    https://github.com/apache/lucy

  Follow the instructions in INSTALL to set up your local workspace.

MAKE CHANGES:

  Edit the source code as you see fit, then build Lucy and run its test suite.

  Please bear the following in mind:

    * 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 must be documented.
    * Code should be formatted according to the style guidelines at
      <http://wiki.apache.org/lucy/LucyStyleGuide>.
    * All unit tests must pass.
    * New code needs to be accompanied by new unit tests.
    * 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. 

OPEN AN ISSUE:

  Lucy's issue-tracker/bug-tracker installation runs Atlassian JIRA and we
  generally use the term "issue" rather than "bug" because not every
  contribution fixes a "bug".
  
     https://issues.apache.org/jira/browse/LUCY
  
  1. Create a JIRA account for yourself and sign in.
  2. Once you have signed in, the "create new issue" link will appear.  Either
     use it to open a new issue or navigate to an existing one as appropriate.
  3. To attach files to an issue, use the menu command
     'More Actions > Attach Files'.

  Attaching a file to an issue causes an email notification to be sent to the
  lucy-issues list signalling that a patch has arrived.  Please be patient but
  persistent while engaging with the Lucy committers who review and apply such
  patches.

CONTRIBUTE A PATCH:

  The easiest way to create a patch with Git is to capture the output of
  `git diff`:

    git diff > my_changes.patch

  The resulting patch file can then be attached to a JIRA issue.

GITHUB PULL REQUESTS

  Github users may submit pull requests against our mirror:

    https://github.com/apache/lucy

  An email notifying the Lucy developers list of your pull request will be
  triggered automatically.