Updated README.md and CONTRIBUTING.md
Project: http://git-wip-us.apache.org/repos/asf/lucenenet/repo Commit: http://git-wip-us.apache.org/repos/asf/lucenenet/commit/743ec24b Tree: http://git-wip-us.apache.org/repos/asf/lucenenet/tree/743ec24b Diff: http://git-wip-us.apache.org/repos/asf/lucenenet/diff/743ec24b Branch: refs/heads/master Commit: 743ec24be5042d2674d01440cfbaddd89032c5fb Parents: bc295b0 Author: Shad Storhaug <[email protected]> Authored: Mon Jul 17 16:50:14 2017 +0700 Committer: Shad Storhaug <[email protected]> Committed: Mon Jul 17 16:50:14 2017 +0700 ---------------------------------------------------------------------- CONTRIBUTING.md | 62 +++++++++++++++++++--------------------------------- README.md | 9 ++++++-- 2 files changed, 29 insertions(+), 42 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucenenet/blob/743ec24b/CONTRIBUTING.md ---------------------------------------------------------------------- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3ce7d4..1ace445 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,50 +1,34 @@ # Lucene.NET Contributor's Guide -Hello new contributors, thanks for getting on board! -Before anything else, please read -[The Getting Involved article at apache.org](https://cwiki.apache.org/confluence/display/LUCENENET/Getting+Involved). In -particular, we will need you to have an ICLA with Apache and to feel -comfortable with Git and GitHub. +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. -You should also be familiar with [Open Source Contribution Etiquette](http://tirania.org/blog/archive/2010/Dec-31.html) and the practice of [Don't "Push" Your Pull Requests](http://www.igvita.com/2011/12/19/dont-push-your-pull-requests/). If you are thinking of making a change that will result in more than 25 lines of changed code, we would appreciate you opening a discussion on our [developer mailing list](https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists) before you start writing. It could save both you and our team quite a bit of work if the code doesn't have to be rewritten to fit in with our overall objectives. +## Getting Started -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](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). +- Read [Open Source Contribution Etiquette](http://tirania.org/blog/archive/2010/Dec-31.html) and [Don't "Push" Your Pull Requests](http://www.igvita.com/2011/12/19/dont-push-your-pull-requests/). +- Make sure you have a [JIRA account](https://cwiki.apache.org/confluence/signup.action). +- Make sure you have a [GitHub account](https://github.com/signup/free). NOTE: Although this is a mirror of our Git repository, pull requests are accepted through GitHub. +- If you are thinking of making a change that will result in more than 25 lines of changed code, we would appreciate you opening a discussion on our [developer mailing list](https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists) before you start writing. It could save both you and our team quite a bit of work if the code doesn't have to be rewritten to fit in with our overall objectives. +- Submit a JIRA ticket for your issue, assuming one doesn't exist already. + - If reporting a bug, clearly describe the issue including steps to reproduce, observed behavior, and expected behavior. + - If reporting a bug, provide source code that we can run without any alteration demonstrating the issue. Issues submitted with runnable code will be given a higher priority than those submitted without. +- If you will be submitting a pull request, fork the repository on GitHub. + - If this is the first time you are contributing, submit an [Individual Contributor License Agreement](https://cwiki.apache.org/confluence/display/LUCENENET/Individual+Contributor+License). + - Create a new descriptive branch (tracking master) and [submit a Pull Request](https://help.github.com/articles/creating-a-pull-request/) once it is ready to be reviewed and merged. + ## If You are Willing to Help with Porting Code -* 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. +* 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](http://www.tangiblesoftwaresolutions.com/Product_Details/Java_to_CSharp_Converter.html). -We have licenses to give to committers) and it proved to work quite nicely, but I also hear good things on Sharpen. [Check it out here](https://github.com/imazen/sharpen) and pick the tool you are more comfortable -with. +* 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](http://www.tangiblesoftwaresolutions.com/Product_Details/Java_to_CSharp_Converter.html) (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](https://github.com/imazen/sharpen) 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.Core, 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. +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 +.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](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/). @@ -54,7 +38,6 @@ Note that even though we are currently a port of Lucene 4.8.0, we recommend port ### Pending being ported from scratch (code + tests) -* [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) @@ -67,9 +50,9 @@ Note that even though we are currently a port of Lucene 4.8.0, we recommend port ### 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). + * Missing native C++ Directory implementations for Windows and Unix/Posix along with wrapper classes to utilize them. See [JIRA issue 562](https://issues.apache.org/jira/projects/LUCENENET/issues/LUCENENET-562) and 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) + * 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 @@ -91,8 +74,7 @@ and <https://github.com/apache/lucenenet/blob/master/src/Lucene.Net.TestFramewor * 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. +* Reviewing code. Pick a random section, review line by line, comparing the code against the [original Lucene 4.8.0 code](https://github.com/apache/lucene-solr/tree/releases/lucene-solr/4.8.0/lucene). 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) or submit a pull request. * 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. http://git-wip-us.apache.org/repos/asf/lucenenet/blob/743ec24b/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index f4c9773..ee56fce 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ The Apache Lucene.Net web site is at: ### Lucene.Net 4.8.0 -- .NET Standard 1.5 (includes .NET Core 1.0 and higher) +- [.NET Standard 1.5](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) - .NET Framework 4.5.1 ### Lucene.Net 3.0.3 @@ -43,6 +43,7 @@ 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](https://www.nuget.org/packages/Lucene.Net/) - Core library - [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 @@ -80,7 +81,7 @@ There are several demos implemented as simple console applications that can be c ## How to Contribute -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. +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. Read our [Contribution Guide](https://github.com/apache/lucenenet/blob/master/CONTRIBUTING.md) or read on for ways that you can help. ### Join Mailing Lists @@ -94,6 +95,10 @@ If you have a general how-to question or need help from the Lucene.Net community We recommend you join the [user mailing list](https://cwiki.apache.org/confluence/display/LUCENENET/Mailing+Lists) to stay looped into all user discussions. +Alternatively, you can get help via [StackOverflow](https://stackoverflow.com/questions/tagged/lucene.net). + +Please do not submit general how-to questions to JIRA, use JIRA for bug reports/tasks only. + ### Report a Bug To report a bug, please use the [JIRA issue tracker](https://issues.apache.org/jira/issues/?jql=project%20%3D%20LUCENENET%20AND%20status%20%3D%20Open). You can signup for a JIRA account [here](https://cwiki.apache.org/confluence/signup.action) (it just takes a minute).
