You have found a bug or you have an idea for a cool new enhancement? Contributing code is a great way to give something back to the open source community. Before you dig right into the code there are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
Please make sure nobody else is working on porting it already. We would like to avoid doing redundant work. We ask that you communicate clearly in this list that you are going to work on some part of the project. A PMC member will then either approve or alert you someone else is working on that part already.
Use automated tools to do the basic porting work, and then start a manual clean-up process. For automatic conversion we are using Tangible's Java to C# Converter (we have licenses to give to committers). It has proven to work quite nicely, but I also hear good things on Sharpen. Check it out here and pick the tool you are more comfortable with.
Conventions & standards: not too picky at this point, but we should definitely align with the common conventions in .NET: PascalCase and not camelCase for method names, properties instead of getters/setters of fields, etc. I'm not going to list all the differences now but we probably want to have such a document up in the future. For reference have a look at Lucene.Net, while not perfect it is starting to shape up the way we want it.
In general, prefer .NETified code over code resembling Java. Enumerators over Iterators, yields when possible, Linq, BCL data structures and so on. We are targeting .NET 4.5.1, use this fact. Sometimes you will have to resort to Java-like code to ensure compatibility; it's ok. We would rather ship fast and then iterate on improving later.
While porting tests, we don't care about all those conventions and .NETification. Porting tests should be reduced to a copy-paste procedure with minimal cleaning up. We are working on tools and code helpers to help with that, see for examples see our Java style methods to avoid many search-replace in porting tests, and a R# plugin that will help making some stuff auto-port when pasting.
Note that even though we are currently a port of Lucene 4.8.0, we recommend porting over new work from 4.8.1. We hope to begin the work of upgrading to 4.8.1 soon (let us know if interested). There are only about 100 files that changed between 4.8.0 and 4.8.1.
We have already managed to get all of the tests green (most of the time). However, there are still a few flaky tests that fail randomly that need to be addressed. Since tests are using randomized testing, failures are changing. But if you put a [Repeat(number)]
attribute on the tests they will fail more often, making them a bit easier to debut.
Some of the code (in particular code in the Support namespace) has no code coverage, and porting/adding tests for those is up for grabs.
Start by cloning Lucene.NET locally. The set VERBOSE to false and you probably may also want to set a constant seed for working locally. See https://github.com/apache/lucenenet/blob/master/src/Lucene.Net.TestFramework/Util/LuceneTestCase.cs#L295 and https://github.com/apache/lucenenet/blob/master/src/Lucene.Net.TestFramework/Util/LuceneTestCase.cs#L610
Note that tests should be run both on .NET Framework and .NET Core. Currently, we have 2 different solutions (Lucene.Net.sln for .NET Framework and Lucene.Net.Portable.sln for .NET Core) that only run in Visual Studio 2015. We are setup to use NUnit 3.x and you will need the appropriate test adapter for Visual Studio to detect the tests. Tests can also be run from the command line using the dotnet test command
Run, debug, iterate. When you think you fixed a bug or a test, please send a PR as fast as possible. There are multiple people working in this area, and we want to make sure your contribution doesn't go stale. Any such PR should have a descriptive name and a short description of what happened and what is your solution. There are some good past examples here.
If we will have comments, we will use GitHub's excellent interface and you will receive notifications also via this list.
LUCENENET TODO|LUCENE TO-DO
using the regular expression option in Visual Studio to find them. Do note there are a lot of TODOs left over from Java Lucene that are safe to ignore.IEnumerator<T>
so they can be used with foreach loops, adding extension methods to remove the need for casting, etc.Also, check out the JIRA issue tracker for any other issues that you might be interested in helping with. You can signup for a JIRA account here (it just takes a minute).
Or, if none of that interests you, join our dev mailing list and ask!
Again, thank you very much for your contribution. May the fork be with you!