[Solr Wiki] Update of "HowToContribute" by ShawnHeisey

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Solr Wiki" for change notification.

The "HowToContribute" page has been changed by ShawnHeisey:
https://wiki.apache.org/solr/HowToContribute?action=diff&rev1=93&rev2=94

Comment:
A bunch of little improvements and cleanups.

  Please keep discussions about Solr on list so that everyone benefits.  Emailing individual committers with questions about specific Solr issues is discouraged.  See http://people.apache.org/~hossman/#private_q.
  
  = Be A Mailing List Moderator =
- Being a [[MailingListModeratorInfo|list moderator]] is incredibly easy - the basic responsibilitie are:
+ Being a [[MailingListModeratorInfo|list moderator]] is incredibly easy - the basic responsibilities are:
  
-  * get a copy of any email sent  to one of the lucene lists from an address that is not subscribed and review it to see if it's spam or not
+  * Get a copy of any email sent to one of the Lucene lists from an address that is not subscribed and review it to see if it's spam or not
-  * occasinally help people with particular difficulties unsubscribing to the mailing list.
+  * Occasionally help people with particular difficulties unsubscribing to the mailing list.
  
  If you'd like to volunteer to be the moderator of a mailing list, just contact `listname-owner@lucene...` (ie: `solr-user-owner@lucene...`)
  
  = Write/Improve User Documentation =
- Solr can always use more/better documentation targeted at end users, most of which is in this wiki where anyone can edit it.  If you see a gap in the Solr documentation, fill it in.  Even if you don't know exactly what to say, ask on the user list and you'll probably get a lot of great responses -- talking informally about how Solr works is something lots of people tend to have time for, but aggregating all of that info into concise cohesive documentation takes a little more work/patience.
+ Solr can always use more/better documentation targeted at end users.  The [[https://cwiki.apache.org/confluence/display/solr/Apache+Solr+Reference+Guide|Reference Guide]] is the official documentation, and only committers can modify it, but anyone can comment on it.  There is quite a lot of additional documentation in this wiki, which anyone can edit after creating an account and asking for edit permissions via the solr-user mailing list or the #solr IRC channel on freenode.
  
+ If you see a gap or problem in the Reference Guide, comment on the page to bring it to the attention of a committer.  If you see a gap or problem in the documentation on this wiki, fill it in.  Even if you don't know exactly what to say, ask on the user list and you'll probably get a lot of great responses -- talking informally about how Solr works is something lots of people tend to have time for, but aggregating all of that info into concise cohesive documentation takes a little more work and patience.
+ 
- If there is a patch in Jira that you think is really great, writing some "user guide" style docs about how it works (or is suppose to work) in the wiki is a great way to help the patch get committed:  It helps serve as a road map for what the "goal" of the issue is, what should be possible for users to do once the issue is resolved; it helps get people who may not understand the low level details get excited about the new functionality; and it can eventually evolve into the final documentation once the code is committed.  (just make sure to link to the issue so people who find your wiki page first know it's not included in Solr's main code line yet).
+ If there is a patch in Jira that you think is really great, writing some "user guide" style docs about how it works (or is suppose to work) in this wiki is a great way to help the patch get committed:  It helps serve as a road map for what the "goal" of the issue is, what should be possible for users to do once the issue is resolved; it helps get people who may not understand the low level details get excited about the new functionality; and it can eventually evolve into the final documentation once the code is committed.  (just make sure to link to the issue so people who find your wiki page first know it's not included in Solr's main code line yet).
  
  = Contributing Code (Features, Bug Fixes, Tests, etc...) =
  This section identifies the ''optimal'' steps community member can take to submit a changes or additions to the Solr code base.  This can be new features, bug fixes optimizations of existing features, or tests of existing code to prove it works as advertised (and to make it more robust against possible future changes).
@@ -96, +98 @@

   * Contributions should pass existing unit tests.
   * New unit tests should be provided to demonstrate bugs and fixes (http://www.junit.org).
  
- == Notes for Eclipse and the New Merged Lucene/Solr checkout ==
+ == Notes for Eclipse ==
- To get correct classpath, formatting, encoding, and project settings in Eclipse, simply run {{{ant eclipse}}} and then reload the project in Eclipse.  Make sure you are using Java 1.6.
+ To get correct classpath, formatting, encoding, and project settings in Eclipse, simply run {{{ant eclipse}}} and then reload the project in Eclipse.  Make sure you are using Java 7 (1.7.x) or later.
  
  == 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.
@@ -147, +149 @@

  {{{
  ant precommit
  }}}
+ 
  === Creating the patch file ===
  Check to see what files you have modified with:
  
  {{{
  svn stat
  }}}
+ 
  Add any new files with:
  
  {{{
  svn add src/.../MyNewClass.java
  }}}
+ 
  Subversions "add" command only modifies your local copy, so it does not require commit permissions.  By using "svn add", your entire contribution can be included in a single patch file, without needing to submit a separate set of "new" files.
  
  If you have a lot of new files you can do "svn add" for all new files in a single command (on "real" OS's only)
@@ -165, +170 @@

  {{{
  svn stat | grep "^?" | awk '{print $2}' | xargs svn add
  }}}
+ 
  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 > SOLR-NNN.patch
+ svn diff > SOLR-NNNN.patch
  }}}
+ 
  This will report all modifications done on Solr sources on your local disk and save them into the ''SOLR-NNN.patch'' file.  Read the patch file.   Make sure it includes ONLY the modifications required to fix a single issue.
  
  Note the ''SOLR-NNN.patch'' patch file name.  Please use this naming pattern when creating patches for uploading to JIRA.  Once you create a new JIRA issue, note its name and use that name when naming your patch file.  For example, if you are creating a patch for a JIRA issue named SOLR-123, then name your patch filename SOLR-123.patch.  If you are creating a new version of an existing patch, use the existing patch's file name.  JIRA will automatically "gray out" the old patch and clearly mark your newly uploaded patch as the latest.
@@ -194, +201 @@

  == Contributing your work ==
  Finally, patches should be attached to a bug report in [[http://issues.apache.org/jira/browse/SOLR|Jira]].  If you are revising an existing patch, please re-use the exact same name as the previous attachment, Jira will "gray out" the older versions so it's clear which version is the newest.
  
- 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 your patch if you think they're reasonable. Remember that even a patch that is not committed is useful to the community. Supply first patch as early as possible and updated patches as often as possible during your work. This helps the rest of the community and committers to start understanding, help shaping, commenting on etc. your work throughout the entire process. Supplying a patch does not necessarily mean that it is complete and ready to be committed, it might also just be a way of communicating your idea and progress.
+ 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 your patch if you think they're reasonable. Remember that even a patch that is not committed is useful to the community. Supply first patch as early as possible and updated patches as often as possible during your work. This helps the rest of the community and committers to start understanding, help shaping, commenting on etc. your work throughout the entire process. Supplying a patch does not necessarily mean that it is complete and ready to be committed, it might also just be a way of communicating your idea and progress.
  
  == JIRA tips (our issue/bug tracker) ==
  The issue tracker we use is a JIRA instance at https://issues.apache.org/jira/browse/SOLR. If you don't yet have an account, just click the "login" link and you'll get the opportunity to create one that will allow you to add tickets, upload patches etc.
@@ -219, +226 @@

  $ wget <URL of the patch>
  $ patch -p0 -i name of the patch --dry-run
  }}}
+ 
  (note: --dry-run just pretends to apply a patch, so you can see if it would succeed or fail.  Remove --dry-run to *really* apply the patch)
  
  The address for the patch can be obtained from the issue page, under the "File Attachments" section of the issue.
@@ -230, +238 @@

  $ svn up
  $ wget <URL to the patch> -O - | patch -p0 --dry-run
  }}}
+ 
  If you are on Solaris, you should replace 'patch' with 'gpatch' to use GNU Patch instead.
  
  If the patch is created using Git, it has another format, which can be applied using {{{-p1}}}:
@@ -237, +246 @@

  {{{
  patch -p1 -i name of the git formatted patch --dry-run
  }}}
+ 
  Reverting to pre-patch state is one line:
  
  {{{
  svn revert -R .
  }}}
+ 
  Though this leaves added files, which can be removed with
  
  {{{
  svn st | grep '?' | awk '{print $2}' | xargs rm
  }}}
+ 
  Another useful trick is to have multiple checkouts of trunk and "bounce" an active changeset from one to another with
  
  {{{
  svn diff | (cd ../otherbranch; patch -p0)
  }}}
+ 
  = Helpful Resources =
  The following resources may prove helpful when developing Solr contributions.  (These are not an endorsement of any specific development tools, but Eclipse and IntelliJ seem to be the most popular)