You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by Apache Wiki <wi...@apache.org> on 2013/07/01 19:24:35 UTC
[Solr Wiki] Trivial Update of "HowToContribute" by ThomasMurphy
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 ThomasMurphy:
https://wiki.apache.org/solr/HowToContribute?action=diff&rev1=88&rev2=89
Comment:
Updated link to Javadoc comments guide (formerly dead link)
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:
* 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
@@ -42, +41 @@
== 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]].
+ Get the source code on your local drive using [[http://lucene.apache.org/solr/version_control.html|SVN]].
To check out code from SVN
+
{{{
svn checkout http://svn.apache.org/repos/asf/lucene/dev/<branch>
}}}
-
The <branch> part of the command above needs to be replaced by something concrete - the "code line" you want to get. Examples, and how to interpret what they mean:
+
* trunk: Working towards a 5.0 release. This is the main center for development, it's not really a branch. Releases are never made from trunk, they are only made from the stable development branch.
* branches/branch_4x: The current development branch for the next stable 4.x version.
* branches/lucene_solr_4_3: Working towards the latest 4.3.x release. There is never a guarantee that a point release will ever be made after the x.x.0 version is released.
* tags/lucene_solr_4_3_0: When a new version is fully released, the lucene_solr_x_x branch is copied to a tag which represents the source code for that specific release.
- * branches/lucene_solr_3_6: When branch_3x was removed and 3.x moved to maintenance mode, all 3.x development moved to this branch.
+ * branches/lucene_solr_3_6: When branch_3x was removed and 3.x moved to maintenance mode, all 3.x development moved to this branch.
SVN revision numbers can be used to obtain branches and tags from their parents. For example, revision 1394844 on branches/lucene_solr_4_0 corresponds to the official 4.0.0 release, so if you add "-r 1394844" to the command line above using branches/lucene_solr_4_0 for <branch>, you will get the code corresponding to 4.0.0. You can also just do a checkout of tags/lucene_solr_4_0_0 to get the same code.
@@ -65, +65 @@
If you prefer you could use the [[https://github.com/apache/lucene-solr|GitHub]] mirror instead. Note that the drop-down lets you select "trunk" or "branch_4x" (among others).
== Exporting to a local repository ==
- When making larger scale (please, try to keep your patches as small as humanly possible) changes, or when working in a team, you might want to be able to keep track of what you are doing locally. One way of doing so, is exporting to a local SVN repository.
+ When making larger scale (please, try to keep your patches as small as humanly possible) changes, or when working in a team, you might want to be able to keep track of what you are doing locally. One way of doing so, is exporting to a local SVN repository.
A proposed strategy for switching/exporting to a local SVN repository;
+
- * get the source from the repository (baseline)
+ * get the source from the repository (baseline)
- * export to local svn (local baseline)
+ * export to local svn (local baseline)
- * loop
+ * loop
- * do work on local baseline (now work)
+ * do work on local baseline (now work)
- * commit
+ * commit
- * draw a line
+ * draw a line
- * do a (unix*) diff of local baseline <-> work (ignore anything that shouldn't go in the patch)
+ * do a (unix*) diff of local baseline <-> work (ignore anything that shouldn't go in the patch)
- * patch apache baseline
+ * patch apache baseline
- * (unix) diff apache baseline <-> work (confirm is empty, or at least looking fine)
+ * (unix) diff apache baseline <-> work (confirm is empty, or at least looking fine)
- * svn diff apache baseline, resulting in final patch
+ * svn diff apache baseline, resulting in final patch
* by doing a unix diff, you keep any local version out of the patch file.
@@ -88, +89 @@
But take care about the following points
- * All public classes and methods should have informative [[http://java.sun.com/j2se/javadoc/writingdoccomments/|Javadoc comments]].
+ * All public classes and methods should have informative [[http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html|Javadoc comments]].
* Code should be formatted according to [[http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html|Sun's conventions]], with some exceptions:
* indent two spaces per level, not four.
* lines can be greater than 80 chars long, 132 is a common limit. Try to be reasonable for ''very'' long lines.
@@ -96, +97 @@
* 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 ==
-
- 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 1.6.
== 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.
@@ -132, +132 @@
One of the great things about Open Source is so many people run the tests on so many different systems. Occasionally you'll be the lucky person who has the system that wins the prize by having the environment that exposes a new failure mode, see the discussion at [[https://issues.apache.org/jira/browse/SOLR-3846|SOLR-3846]] for an example.
If you do find one of these, here's what you should do:
+
* First, just try running 'ant -Dtests.badapples=false test'. If the tests succeed, this is a known issue that we haven't found a solution for yet, but want to gather information about. If you have the time, ping the dev list and include your setup details. But in the case where setting this flag causes the tests to succeed, you can assume that your code changes didn't cause this error and go ahead.
* If tests continue to fail, ask on the dev list if anyone else has seen the issue. This is the case where having the un-changed code helps. If the tests fail on both the changed and un-changed versions, discuss on the dev list whether the test can be annotated as a 'badapples' test or not.
* If tests fail with your changes but not on un-altered code, well, you need to understand why. By far the most frequent reason is a bug or unintended side-effect of your code, but occasionally it's a test that needs modification. Again, the dev list is a good place to discuss this.
@@ -139, +140 @@
* Of course any effort you want to make towards tracking down the reason a test fails in your particular environment is greatly appreciated!
=== Pre-commit check ===
+ Before constructing your patch, please run the top-level pre-commit check, which finds problems like tabs and @author tags in source files, broken links in javadocs, files not controlled by Subversion (a.k.a. "unversioned files"), etc.
+ To run the pre-commit checks from ant, run the following from the top-level directory -- the directory containing {{{lucene/}}} and {{{solr/}}} -- in your working copy:
- Before constructing your patch, please run the top-level pre-commit check, which
- finds problems like tabs and @author tags in source files, broken links in
- javadocs, files not controlled by Subversion (a.k.a. "unversioned files"), etc.
-
- To run the pre-commit checks from ant, run the following from the top-level directory
- -- the directory containing {{{lucene/}}} and {{{solr/}}} -- in your working copy:
{{{
ant precommit
}}}
-
=== Creating the patch file ===
Check to see what files you have modified with:
@@ -165, +161 @@
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)
+
{{{
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:
@@ -237, +233 @@
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}}}:
+
{{{
patch -p1 -i name of the git formatted patch --dry-run
}}}
-
Reverting to pre-patch state is one line:
{{{
@@ -287, +283 @@
||3.5 ||http://svn.apache.org/repos/asf/lucene/dev/branches/lucene_solr_3_5/dev-tools/maven/README.maven ||
||trunk/4.0 (unreleased) ||http://svn.apache.org/repos/asf/lucene/dev/trunk/dev-tools/maven/README.maven ||
+
+
+
== Getting your feet wet: where to begin? ==
-
New to Solr? Want to find JIRA issues that you can work on without taking on the whole world?
The Solr/Lucene developers use the "newdev" label to mark issues that developers new to Solr might be interested in working on. The rough criteria used to make this selection are:
@@ -297, +295 @@
* The issue is likely not controversial.
* The issue is likely self-contained with limited scope.
- To see a list of open Solr and Lucene issues with the newdev label, look at this link [[http://s.apache.org/newdevlucenesolr|http://s.apache.org/newdevlucenesolr]]
+ To see a list of open Solr and Lucene issues with the newdev label, look at this link http://s.apache.org/newdevlucenesolr
'''Note:''' Fixing these issues may require asking questions on the developer list to figure out what they mean - there is no guarantee that any of these will be either quick or easy.
== Parsers and JFlex ==
'''YOU PROBABLY DON'T HAVE TO DO THIS''' but if you do for some reason want to regenerate the .java from the .jflex files, here's the cheat-sheet. This is a separate step that people who actually ''like'' parsers sometimes have to execute to reflect changes in various grammars.
+
* Check out the most recent jflex branch. This is important since what Lucene uses is based on trunk rather than a released version (thanks for tutoring me Uwe!). Do this by executing: svn co https://jflex.svn.sourceforge.net/svnroot/jflex/trunk jflex
* cd jflex
* mvn install (NOTE: I've seen the tests fail in this step, doesn't seem to matter)
* cd <solr_home>/lucene/analysis/common
- * export ANT_OPTS="-Xmx1G -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=1G" (1)
+ * export ANT_OPTS="-Xmx1G -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=1G" (1)
* ant jflex
(1) I was getting OOM errors when running "ant jflex", and got a tip to do this, which made that problem go away. You may not have to be so generous with memory, but this worked... (Thanks Steve!).