This document describes the conditions and manner in which a Lucene/Solr committer may commit (git commit, merge and push) new changes to non-feature branches (e.g. to master).  "You" in this document is the committer wishing to make changes.  This policy does not apply to contributors, as they do not have permissions.  Feature branches are WIP that don't directly ship to a release and so there is no policy.

TODO We also discuss some related matters like the commit message and JIRA issues.

Despite the word "Policy" which is suggestive of rules, this document is really a guideline document.  There is a lot of trust between committers; in some cases it may make sense to diverge from these policies.  We try to articulate here when that makes sense.  When in doubt, ask on the dev-list.

Reviews

From an ASF policy perspective, this project follows CTR (Commit-Then-Review) which grants committers permission to commit at will, with the possibility of being retroactively vetoed.  However, in practice code is peer-reviewed before-hand most of the time, and so this project might appear to be the reverse of that.  Strictly speaking, this project does not follow RTC (Review-Then-Commit) which has onerous qualifications we don't wish to adhere to.

...

Reviews are usually but not always required. When changes are sufficiently minor (low risk, low consequence, not controversial), don't let such processes get in the way of immediate/timely progress.  It needs to be minor enough that it's not worth mentioning in CHANGES.txt.  You probably shouldn't bother waiting for a review for these circumstances:

• Bug fixes (trivial)
• Extensibility improvements that are trivial (e.g. protected/public) on classes that are already marked with lucene.internal or lucene.experimental (or Solr classes/methods deemed similarly even if not annotated).
• Formatting / indentation
• Typo/grammar corrections
• Documentation and code comments
• Error or log message improvement
• Tests, especially additional tests
• dev-tools/

It needs to be minor enough that it's not worth mentioning in CHANGES.txt.  Yet Yet for any guidelines, there are counter-examples.  Are you intending to auto-indent the entire codebase or do any change affecting many files?  Discuss it first.  Are you doing a intra-page re-organization of documentation?  Try to get a review.  Will your change impact backwards-compatibility?  This requires a review and mention it so it's clear in the JIRA issue.  Adding a new dependency (not just an update)?  Call it out in the JIRA issue; get a review.

Please avoid making lots of little minor commits too.  This is more a matter of taste in reflection of years of our practices.

JIRA has a Priority field with values Minor and Trivial, among others.  We don't differentiate them here; depending on the issue, either values might meet our loose definitions here to skip a review.  

TODO mention not needing a JIRA issue for these scenarios as well?  Such a proposal needn't block a GitHub PR I suppose, and thus not all  GH PRs need a JIRA issue.

Tests

There is no real policy on tests, but obviously, we want our code to be tested.  If the proposed changes don't incorporate a test then the issue or GitHub PR (or other review platform) should mention so and why for the benefit of reviewers, unless it's obviously not needed (e.g. already tested via whatever).  Trivial bugs need not.

Bug fix commits should include at least one test that does not pass without the accompanying fix.

Documentation

TODO All new Features should be accompanied by new documentation (at a minimum, mention on the wiki)

There isn't much policy on docs except for what the build enforces relating to required presence of javadocs on public classes/methods.  Solr does not have that same enforcement but we view this as technical debt, at least at a class file level.  For Solr, consider the impact of your change on the reference guide.  Most features and improvements should update the ref guide accordingly.

Updating CHANGES.txt

If the change was not minor (see above RE "When Reviews Aren't Needed"), add an entry to CHANGES.txt.  Choose a suitable category to add your entry generally consistent with that of the JIRA issue (although it's not 1-1 at present).  Follow the formatting style you see.  If there's a backwards-compatibility / upgrading concern, be sure to add an extra entry in that category.

Remember that the audience of this file serves both users and fellow committers. Consider that in use of jargon / detail, yet be brief.  Readers can always read the linked JIRA issue.

Give credit to the those involved with the issue in order of decreasing importance.  There is no guidance on how to deem which participants are worth a mention at all though.  Sometimes committers do not even credit themselves for committing the work of a contributor.  Some do but after a "via".  Try to refer to people in a consistent way by searching for pre-existing reference in the file; some committers prefer their first and last name, some prefer an apache user ID.

Commit message

Start a commit message with the JIRA issue ID, then a colon, space, then a one-liner brief summary.  You are encouraged to add further notes on additional lines to the extent you feel is helpful.  Commits frequently include various supporting changes; the commit message is a great place to list them.

If the work is primarily that of a contributor, use their name in the "Author" metadata.  If you can't because you don't have their email address, then mention them in the message.

Linear History in Git

We prefer linear history in our source control (Git) for ease of comprehension.  Assuming you think your change shouldn't be an exception, then ensure your commit is added on top instead of creating a loop.

TODO add tip on how to do this.

TODO TODO triage below old content

Architectural or "Weighty" Changes to the "Guts" of Solr

...

if an architectural or other serious internal change requires changes to existing unit tests, that should be pointed out and the potential ramifications for existing end users should be discussed thoroughly on the Solr developer list.

Non-Backwards Compatible Changes to Functionality or APIs

Changes to Solr's public APIs (either via URL structure, or APIs exposed to Plugin Developers) should always be tracked as a patch in the issue tracking system under the RTC model. Potential ramifications for existing end users should be discussed thoroughly on the Solr user list.

Changes of this scope should result in a Major Version increase (ie: 1.x to 2.0)