lucene-solr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Solr Wiki] Update of "HowToContribute" by chrismattmann
Date Mon, 05 Apr 2010 21:16:27 GMT
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 chrismattmann.
The comment on this change is: some dev notes from IRC on getting Lucene/Solr to build..
http://wiki.apache.org/solr/HowToContribute?action=diff&rev1=35&rev2=36

--------------------------------------------------

  = How to Contribute to Solr =
- 
  "Contributing" to an Apache project is about more then just writing code -- it's about doing
what you can to make the project better.  There are lots of ways to contribute....
  
  <<TableOfContents>>
  
  = Be Involved =
+ Contributors should join the [[http://lucene.apache.org/solr/mailing_lists.html|Solr mailing
lists]].  In particular:
  
- Contributors should join the [[http://lucene.apache.org/solr/mailing_lists.html|Solr mailing
lists]].  In particular:
-    * the user list (to help others)
+  * the user list (to help others)
-    * The commit list (to see changes as they are made) 
+  * The commit list (to see changes as they are made)
-    * The dev list (to join discussions of changes) 
+  * The dev list (to join discussions of changes)
  
  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.
  
  = 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.
  
  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).
  
  = Contributing Code (Features, Big 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).
  
  Please note that these are the "optimal" steps, and community members that don't have the
time or resources to do everything outlined on this below should not be discouraged from submitting
their ideas "as is" per "Yonik's Law of Patches" ...
  
  {{{
- A half-baked patch in Jira, with no documentation, no tests 
+ A half-baked patch in Jira, with no documentation, no tests
  and no backwards compatibility is better than no patch at all.
  }}}
- 
  Just because you may not have the time to write unit tests, or cleanup backwards compatibility
issues, or add documentation, doesn't mean other people don't. Putting your patch out there
allows other people to try it and possibly improve it.
  
  == Getting the source code ==
- 
  First of all, you need the Solr source code.<<BR>>
  
- Get the source code on your local drive using 
- [[http://lucene.apache.org/solr/version_control.html|SVN]].  Most development is done on
the "trunk":
+ Get the source code on your local drive using  [[http://lucene.apache.org/solr/version_control.html|SVN]].
 Most development is done on the "trunk":
  
  {{{
- > svn checkout http://svn.apache.org/repos/asf/lucene/solr/trunk
+ > svn checkout http://svn.apache.org/repos/asf/lucene/dev/trunk
  }}}
- 
  Note that committers have to use [[http://apache.org/dev/committers.html#commit-403|https]]
instead of http here, but http is fine for read-only access to the trunk code.
  
  == Making Changes ==
- 
  Before you start, you should send a message to the [[http://lucene.apache.org/solr/mailing_lists.html|Solr
developer mailing list]] (Note: you have to subscribe before you can post), or file a bug
in [[http://issues.apache.org/jira/browse/SOLR|Jira]].  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 and add some (very) nice features using your favorite IDE.<<BR>>
+ Modify the source code and add some (very) nice features using your favorite IDE.
  
  But take care about the following points
+ 
   * All public classes and methods should have informative [[http://java.sun.com/j2se/javadoc/writingdoccomments/|Javadoc
comments]].
   * Code should be formatted according to [[http://java.sun.com/docs/codeconv/|Sun's conventions]],
with one exception:
    * indent two spaces per level, not four.
   * Contributions should pass existing unit tests.
-  * New unit tests should be provided to demonstrate bugs and fixes ([[http://www.junit.org]]).
+  * 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 == 
+ 
+ Having trouble getting the new Lucene/Solr checkout to work in Eclipse? Do you see some
errors having to do with:
+ 
+ {{{
+ org.w3c.dom.Node#getTextContent() not found
+ }}}
+ 
+ in the solr/src/test/TestConfig.java file? This has to do with the Tidy.jar library which
includes its own version of the Node API. By removing Tidy.jar from your Eclipse classpath,
you can obviate this problem.
+ 
+ Another issue you may see is character encoding, especially if you are including the lucene/contrib/analyzers
package. On Eclipse, you can solve this by going to Project > Properties > Resources,
and then changing the encoding on that page to UTF-8. Then let Eclipse rebuild the workspace
(either automatically if you have that checked, or force a rebuild) and you should be golden!
+ 
+ (thanks to Mark Miller and Erik Hatcher for contributing to this)
+ 
  
  == 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.
  
  === Unit Tests ===
- 
  Please make sure that all unit tests succeed before constructing your patch.
  
  {{{
@@ -73, +79 @@

  > ant clean test
  }}}
  After a while, if you see
+ 
  {{{
  BUILD SUCCESSFUL
  }}}
  all is ok, but if you see
+ 
  {{{
  BUILD FAILED
  }}}
  please, read carefully the errors messages and check your code. If the test fails you may
want to repeatedly rerun a single test as you debug and sort out any problems. In which case
you could run
+ 
  {{{
  > ant -Dtestcase=TestXXX test
  }}}
  Where "TestXXX" is the name of the particular Junit test you want to run.
  
  === Creating the patch file ===
+ Check to see what files you have modified with:
  
- Check to see what files you have modified with:
  {{{
  svn stat
  }}}
+ Add any new files with:
  
- 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.
  
  Edit the ''CHANGES.txt'' file, adding a description of your change, including the bug number
it fixes.
@@ -107, +115 @@

  {{{
  svn diff > SOLR-NNN.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.  
+ 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.
- 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.
  
  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.  
+  * 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.
-  * Combine multiple issues into a single patch, especially if they are unrelated or only
loosely related.  This is true even if the changes affect the same files.  In some rare cases
it is warranted, but for the most part it makes it harder for committers to evaluate the patch.

+  * Combine multiple issues into a single patch, especially if they are unrelated or only
loosely related.  This is true even if the changes affect the same files.  In some rare cases
it is warranted, but for the most part it makes it harder for committers to evaluate the patch.
  
  Please do:
+ 
   * try to adhere to the coding style of files you edit;
   * comment code whose function or rationale is not obvious;
   * update documentation (e.g., ''package.html'' files, this wiki, etc.)
   * try to provide a unit test that shows a bug was indeed fixed or the new functionality
truly works
  
  == 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 into
your patch if you think they're reasonable.  Finally, remember that even a patch that is not
committed is useful to the community.
@@ -135, +142 @@

  == JIRA tips (our issue/bug tracker) ==
  The issue tracker we use is a JIRA instance at https://issues.apache.org/jira/browse/SOLR
  
-   * When creating new issues in JIRA, please keep the "Description" field short - every
change or followup on the issue will cause an email to be sent to the solr-dev mailing list,
and will include the complete Description every time.
+  * When creating new issues in JIRA, please keep the "Description" field short - every change
or followup on the issue will cause an email to be sent to the solr-dev mailing list, and
will include the complete Description every time.
-   * When attaching newer versions of a file/patch, use the same name... JIRA will "gray
out" the older versions automatically.
+  * When attaching newer versions of a file/patch, use the same name... JIRA will "gray out"
the older versions automatically.
-   * Please do not delete older files that you have already added - the complete history
of an issue is important.
+  * Please do not delete older files that you have already added - the complete history of
an issue is important.
-   * If you aren't sure if something is a bug, please ask on the solr-user mailing list before
opening an issue.
+  * If you aren't sure if something is a bug, please ask on the solr-user mailing list before
opening an issue.
- 
  
  <<Anchor(TestingPatches)>>
+ 
  = Review/Improve Existing Patches =
- 
  If there's a Jira issue that already has a patch you think is really good, and works well
for you -- please add a comment saying so.   If there's room for improvement (more tests,
better javadocs, etc...) then make the changes and attach it as well.  If a lot of people
review a patch and give it a thumbs up, that's a good sign for committers when deciding if
it's worth spending time on the patch -- and if other people have already put in effort to
improve the docs/tests for a patch, that helps even more.
  
  == Working With Patches ==
- 
  You can easily download a patch from JIRA and test it by doing the following:
  
  {{{
@@ -156, +161 @@

  $ 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.
@@ -168, +172 @@

  $ 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.
  
  Reverting to pre-patch state is one line:
+ 
  {{{
  svn revert -R .
  }}}
+ Though this leaves added files, which can be removed with
  
- 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
  
- 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)
  
-    * [[attachment:Eclipse.3.2.codestyle.xml|Eclipse 3.2 codestyle.xml file for Solr's coding
conventions]]
+  * [[attachment:Eclipse.3.2.codestyle.xml|Eclipse 3.2 codestyle.xml file for Solr's coding
conventions]]
-    * [[attachment:IntelliJ.codestyle.xml|IntelliJ IDEA codestyle.xml file for Solr's coding
conventions]]
+  * [[attachment:IntelliJ.codestyle.xml|IntelliJ IDEA codestyle.xml file for Solr's coding
conventions]]
  
- <!> [[Solr1.3]]
- If you are using eclipse to follow trunk (leading up to the 1.3 release) eclipse will give
several errors about not resolving components in the solrj library. This will appear in the
org.apache.solr.handler.component package relating to distributed search (sharedrequest.java
...etc) The solution is to compile the solrj library via the dist-solrj target and add them
to your eclipse build path. After running the dist-solrj target look in dist/solrj-lib and
add apache-solr-solrj-1.3-dev.jar and commons-httpclient-3.1.jar to your buildpath.
+ <!> [[Solr1.3]] If you are using eclipse to follow trunk (leading up to the 1.3 release)
eclipse will give several errors about not resolving components in the solrj library. This
will appear in the org.apache.solr.handler.component package relating to distributed search
(sharedrequest.java ...etc) The solution is to compile the solrj library via the dist-solrj
target and add them to your eclipse build path. After running the dist-solrj target look in
dist/solrj-lib and add apache-solr-solrj-1.3-dev.jar and commons-httpclient-3.1.jar to your
buildpath.
  
  DevelopmentEnvironmentTips
  

Mime
View raw message