Updated README.md and CONTRIBUTING.md with latest status, improved readability, and more helpful links
Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/9a8c9f20 Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/9a8c9f20 Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/9a8c9f20 Branch: refs/heads/master Commit: 9a8c9f2038ace98197d1ca3519b77c2d368a0f18 Parents: ba73b76 Author: Shad Storhaug <[email protected]> Authored: Fri Jul 7 02:51:55 2017 +0700 Committer: Shad Storhaug <[email protected]> Committed: Fri Jul 7 02:51:55 2017 +0700 ---------------------------------------------------------------------- CONTRIBUTING.md | 66 +++++++++++++++++++++++++++++++--------------------- README.md | 41 ++++++++++++++++++++++++++++---- 2 files changed, 75 insertions(+), 32 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucenenet/blob/9a8c9f20/CONTRIBUTING.md ---------------------------------------------------------------------- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 95019c5..e3ce7d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ You should also be familiar with [Open Source Contribution Etiquette](http://tir Start by forking [Lucene.NET on GitHub](https://github.com/apache/lucenenet). For every contribution you are about to make, you should create a branch (tracking -master!) with some descriptive name, and send us a Pull Request once it is +master!) with some descriptive name, and [send us a Pull Request](https://help.github.com/articles/creating-a-pull-request/) once it is ready to be reviewed and merged. And please git rebase when pulling from origin/master instead of merging :) [More information can be found over at Atlassian](https://www.atlassian.com/git/tutorials/rewriting-history/git-rebase). @@ -48,49 +48,61 @@ 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](https://github.com/apache/lucenenet/tree/master/src/Lucene.Net.TestFramework/JavaCompatibility), and a [R# plugin that will help making some stuff auto-port when pasting](https://resharper-plugins.jetbrains.com/packages/ReSharper.ExJava/). -### Code that is currently pending being ported from scratch (+ tests) == up for grabs: +## Porting Work - Up For Grabs -* [Lucene.Net.Demo](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/demo) (might be a good learning experience) -* [Lucene.Net.Replicator](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/replicator) -* [Lucene.Net.Analysis.ICU](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/analysis/icu) (note that we will be putting this functionality into the Lucene.Net.ICU package) -* [Lucene.Net.Analysis.Kuromoji](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/analysis/kuromoji) +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. -There are a few other specialized packages ([Analysis.Morfologik](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/analysis/morfologik), [Analysis.UIMA](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/analysis/uima), [Benchmark](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/benchmark)) that have dependencies that would also need to be ported if they don't exist in .NET yet. +### Pending being ported from scratch (code + tests) -There are several command-line utilities for tasks such as maintaining indexes that just need to be put into a console application and "usage" documentation updated for them to be useful (which might be helpful for those who don't want to install Java to run such utilities from the Lucene project). See the [JIRA Issues](https://issues.apache.org/jira/issues/?jql=project%20%3D%20LUCENENET%20AND%20status%20%3D%20Open%20AND%20text%20~%20%22CLI%22) for the current list. +* [Lucene.Net.Replicator](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/replicator) - See [JIRA issue 565](https://issues.apache.org/jira/browse/LUCENENET-565) (in progress) +* [Lucene.Net.Analysis.ICU](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/analysis/icu) - See [JIRA issue 566](https://issues.apache.org/jira/browse/LUCENENET-566) +* [Lucene.Net.Analysis.Kuromoji](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/analysis/kuromoji) - See [JIRA issue 567](https://issues.apache.org/jira/browse/LUCENENET-567) -The [Lucene.Net.Misc](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/misc) project has some native C++ directories for Windows and Unix/Posix along with wrapper classes to utilize them (in the Store namespace) that are not yet ported, and the [Lucene.Net.Sandbox](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene/sandbox) project is still incomplete. +### Pending being ported from scratch (code + tests), but have additional dependencies that also either need to be sourced from the .NET ecosystem or ported. + +* [Lucene.Net.Benchmark](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/benchmark) - See [JIRA issue 564](https://issues.apache.org/jira/browse/LUCENENET-564) +* [Lucene.Net.Analysis.Morfologik](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/analysis/morfologik) - See [JIRA issue 568](https://issues.apache.org/jira/browse/LUCENENET-568) +* [Lucene.Net.Analysis.UIMA](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/analysis/uima) - See [JIRA issue 570](https://issues.apache.org/jira/browse/LUCENENET-570) + +### Partially Completed + +* [Lucene.Net.Misc](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/misc) + * Missing native C++ Directory implementations for Windows and Unix/Posix along with wrapper classes to utilize them. See the [Store namespace](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/misc/src/java/org/apache/lucene/store). +* [Lucene.Net.Sandbox](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.1/lucene/sandbox) + * Missing all of the SlowCollatedXXX classes, the RegEx namespace (+ related tests). (casing intentional to prevent naming collisions with .NET Regex class) ## If you are more into Fixing Existing Tests -We have already managed to get all of the tests green (most of the time). However, there are still a few [flaky tests](https://teamcity.jetbrains.com/project.html?projectId=LuceneNet_PortableBuilds&tab=flakyTests) that fail randomly that need to be addressed. Since tests are using randomized testing, failures are changing. +We have already managed to get all of the tests green (most of the time). However, there are still a few [flaky tests](https://teamcity.jetbrains.com/project.html?projectId=LuceneNet_PortableBuilds&tab=flakyTests) 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> +* 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](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.NUnit3TestAdapter) for Visual Studio to detect the tests. Tests can also be run from the command line using the [dotnet test](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-test) command -* 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 and onwards. We are setup to use NUnit 3.x and you will need the appropriate [test adapter](https://marketplace.visualstudio.com/items?itemName=NUnitDevelopers.NUnit3TestAdapter) for Visual Studio to detect the tests. Tests can also be run from the command line using the [dotnet test](https://docs.microsoft.com/en-us/dotnet/core/tools/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](https://github.com/apache/lucenenet/pulls?q=is%3Apr+is%3Aclosed). -* 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](https://github.com/apache/lucenenet/pulls?q=is%3Apr+is%3Aclosed). +* If we will have comments, we will use GitHub's excellent interface and you will receive notifications also via this list. -* If we will have comments, we will use github's excellent interface and -you will receive notifications also via this list. +## Other Ways To Help -## Other types of help +* Making demos and tutorials, blogging about Lucene.Net, etc. (and providing feedback on how we can make the API better!). If you write a helpful Lucene.Net post on your blog, be sure to let us know so we can link to it. +* Helping out with documentation. We are still trying to make the API docs easily navigable (see #206), and there are many files that are not formatted correctly (links not appearing, tables not very readable, etc). Also, we need help getting all of the Java-related documentation converted to use .NET methodologies. +* Reviewing code. Pick a random section, review line by line. Many of the bugs have been found this way, as the tests are not showing them. Let us know if you find anything suspicious on the [dev mailing list](https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists). +* Create a new Lucene.Net web site. Our [current one](https://lucenenet.apache.org/) is ridiculously out of date and could use a mobile-friendly finish. We could probably also use a refresher on our logo. This project was on our radar for a while but somehow died. Join our [dev mailing list](https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists), gather requirements, and you will be well on your way. +* Optimizing code. During porting we have ended up with some code that is less than optimal. We could use a hand getting everything up to speed (pun intended). +* Helping update the API, or at least just providing feedback on what is important. There are several things on our radar, like integrating something like [Lucene.Net.Linq](https://github.com/themotleyfool/Lucene.Net.Linq) directly into our project, [converting the remaining public-facing iterator classes into `IEnumerator<T>`](https://issues.apache.org/jira/projects/LUCENENET/issues/LUCENENET-469?filter=allopenissues) so they can be used with foreach loops, adding extension methods to remove the need for casting, etc. +* Creating projects to make Lucene.Net easier to use with various .NET frameworks (ASP.NET MVC, WebApi, AspNetCore, WPF, EntityFramework, etc). In general, we would like common tasks as easy as possible to integrate into applications build on these frameworks without everyone having to write the same boilerplate code. +* Building automation tools to eliminate some of the manual work of managing the project, updating information on various web pages, creating tools to make porting/upgrading more automated, etc. +* Be a power beta tester. Make it your mission to track down bugs and report them to us on [JIRA](https://issues.apache.org/jira/issues/?jql=project%20%3D%20LUCENENET%20AND%20status%20%3D%20Open). -We will definitely need more help (like optimizing code, normalizing tabs/spaces, writing tutorials, helping with API documentation, automating stuff, etc) but we are not there yet! +Also, check out the [JIRA issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20LUCENENET%20AND%20status%20%3D%20Open) for any other issues that you might be interested in helping with. You can signup for a JIRA account [here](https://cwiki.apache.org/confluence/signup.action) (it just takes a minute). -Also, check out the [JIRA issue tracker](https://issues.apache.org/jira/browse/LUCENENET-586?jql=project%20%3D%20LUCENENET%20AND%20status%20%3D%20Open%20AND%20assignee%20in%20(EMPTY)) for any other issues that you might be interested in helping with. You can signup for a JIRA account [here](https://cwiki.apache.org/confluence/signup.action) (it just takes a minute). +Or, if none of that interests you, join our [dev mailing list](https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists) and ask! -## Thank You! +## Thank You For Your Help! Again, thank you very much for your contribution. May the fork be with you! \ No newline at end of file http://git-wip-us.apache.org/repos/asf/lucenenet/blob/9a8c9f20/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index 34ab64f..6c08308 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Apache Lucene.Net -Apache Lucene.Net is a .NET full-text search engine, a C# port of the popular Apache Lucene project. Apache Lucene.Net is not a complete application, but rather a code library and API that can easily be used to add search capabilities to applications. +## Full-text search for .NET + +Apache Lucene.Net is a .NET full-text search engine framework, a C# port of the popular Apache Lucene project. Apache Lucene.Net is not a complete application, but rather a code library and API that can easily be used to add search capabilities to applications. The Apache Lucene.Net web site is at: http://lucenenet.apache.org @@ -9,7 +11,7 @@ The Apache Lucene.Net web site is at: ### Lucene.Net 4.8.0 -- .NET Standard 1.5 +- .NET Standard 1.5 (includes .NET Core 1.0 and higher) - .NET Framework 4.5.1 ### Lucene.Net 3.0.3 @@ -31,22 +33,51 @@ Working toward Lucene.Net 4.8.0 (currently in BETA) PM> Install-Package Lucene.Net ``` -As of 4.8.0, Lucene.Net is now divided into several NuGet sub-packages. See the [complete list of Lucene.Net sub-packages on NuGet.org](https://www.nuget.org/packages?q=lucene.net) +Or, to install the BETA of 4.8.0, run + +``` +PM> Install-Package Lucene.Net -Pre +``` + +As of 4.8.0, Lucene.Net is now divided into several specialized sub-packages, all available on NuGet. +<!--- TO BE ADDED WHEN RELEASED - [Lucene.Net.Analysis.Phonetic](https://www.nuget.org/packages/Lucene.Net.Analysis.Phonetic/) - Analyzer for indexing phonetic signatures (for sounds-alike search) ) +- [Lucene.Net.Analysis.SmartCn](https://www.nuget.org/packages/Lucene.Net.Analysis.SmartCn/) - Analyzer for indexing Chinese)--> +- [Lucene.Net.Analysis.Common](https://www.nuget.org/packages/Lucene.Net.Analysis.Common/) - Analyzers for indexing content in different languages and domains +- [Lucene.Net.Analysis.Stempel](https://www.nuget.org/packages/Lucene.Net.Analysis.Stempel/) - Analyzer for indexing Polish +- [Lucene.Net.Classification](https://www.nuget.org/packages/Lucene.Net.Classification/) - Classification module for Lucene +- [Lucene.Net.Codecs](https://www.nuget.org/packages/Lucene.Net.Codecs/) - Lucene codecs and postings formats +- [Lucene.Net.Expressions](https://www.nuget.org/packages/Lucene.Net.Expressions/) - Dynamically computed values to sort/facet/search on based on a pluggable grammar +- [Lucene.Net.Facet](https://www.nuget.org/packages/Lucene.Net.Facet/) - Faceted indexing and search capabilities +- [Lucene.Net.Grouping](https://www.nuget.org/packages/Lucene.Net.Grouping/) - Collectors for grouping search results +- [Lucene.Net.Highlighter](https://www.nuget.org/packages/Lucene.Net.Highlighter/) - Highlights search keywords in results +- [Lucene.Net.ICU](https://www.nuget.org/packages/Lucene.Net.ICU/) - Specialized international support for languages that don't space words +- [Lucene.Net.Join](https://www.nuget.org/packages/Lucene.Net.Join/) - Index-time and Query-time joins for normalized content +- [Lucene.Net.Memory](https://www.nuget.org/packages/Lucene.Net.Memory/) - Single-document in-memory index implementation +- [Lucene.Net.Misc](https://www.nuget.org/packages/Lucene.Net.Misc/) - Index tools and other miscellaneous code +- [Lucene.Net.Queries](https://www.nuget.org/packages/Lucene.Net.Queries/) - Filters and Queries that add to core Lucene +- [Lucene.Net.QueryParser](https://www.nuget.org/packages/Lucene.Net.QueryParser/) - Text to Query parsers and parsing framework +- [Lucene.Net.Sandbox](https://www.nuget.org/packages/Lucene.Net.Sandbox/) - Various third party contributions and new ideas +- [Lucene.Net.Spatial](https://www.nuget.org/packages/Lucene.Net.Spatial/) - Geospatial search +- [Lucene.Net.Suggest](https://www.nuget.org/packages/Lucene.Net.Suggest/) - Auto-suggest and Spellchecking support ## Documentation [Lucene.Net WIKI](https://cwiki.apache.org/confluence/display/LUCENENET/Lucene.Net) -We don't yet have API documentation for Lucene.Net 4.8.0, but the API is similar to [Lucene 4.8.0](https://lucene.apache.org/core/4_8_0/). +We don't yet have API documentation for Lucene.Net 4.8.0, but the API is similar to [Lucene 4.8.0](https://lucene.apache.org/core/4_8_0/). NOTE: We are working on this, but could use more help since it is a massive project. See #206. ### Legacy Versions - [Lucene.Net 3.0.3 API Documentation](http://incubator.apache.org/lucene.net/docs/3.0.3/Index.html) - [Lucene.Net 2.9.4 API Documentation](http://incubator.apache.org/lucene.net/docs/2.9.4/Index.html) +## Demos + +There are several demos implemented as simple console applications that can be copied and pasted into Visual Studio or compiled on the command line in the [Lucene.Net.Demo project](https://github.com/apache/lucenenet/tree/master/src/Lucene.Net.Demo). + ## How to Contribute -Lucene is a very large project (over 350,000 executable lines of code) and we welcome any and all help to maintain such an effort. +Lucene.Net is a very large project (over 400,000 executable lines of code and nearly 1,000,000 lines of text total) and we welcome any and all help to maintain such an effort. ### Join Mailing Lists
