NightOwl888 opened a new issue #457: URL: https://github.com/apache/lucenenet/issues/457
Based on the Lucene demo document here: https://github.com/apache/lucenenet/blob/Lucene.Net_4_8_0_beta00014/src/Lucene.Net.Demo/overview.md it is clear that there are gaps in my knowledge of how these demos were meant to be delivered to Java developers and how we can provide an optimal experience in .NET. ### What Lucene does * The demo "package" is shipped as compiled code and [hosted on Maven](https://search.maven.org/search?q=a:lucene-demo) * The documentation seems to assume that you know how to get from there to "adjust your classpath" to being able to run from the command line, without giving much detail about how * It is not clear whether the command line is run against a compiled .jar file or if they are building from source ### How we "ported" it * We don't ship the Lucene.Net.Demo package on NuGet * Since it is not possible to "run" a .NET Standard assembly, the demos were compiled into a .NET Core 3.1 console application named `lucene-cli`. * We compile the code from the Lucene.Net.Demo project into lucene-cli and ship that on NuGet. The demos can be run directly from the console, provided the right input options are provided (which have all been documented in the `lucene-cli` docs). * The code is also embedded as resources inside of lucene-cli so it can be exported on disk by running the [`--output-source-code`](https://lucenenet.apache.org/docs/4.8.0-beta00014/cli/demo/index-files.html) option * There are references in the documentation that link to the code files in the Lucene.Net.Demo project in the repository so the user has an alternate way to see the demo code than installing `lucene-cli` * Most of the demo code has also been added to Markdown files (https://github.com/apache/lucenenet/issues/284#issuecomment-806268971), but AFAIK these are not being referenced in other documentation ### Problems * The demos are not mentioned anywhere on the home page, you have to drill down pretty deep in the documentation to find them * The source code alone is not enough for the user to take advantage of it by using [`dotnet run`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-run) or putting it in Visual Studio (a `.csproj` file is also required, I believe, but there may also be other dependencies to investigate) * The links to the demo source code are not functional yet because `docs.ps1` build doesn't replace the tags in URLs * Keeping the demos in Markdown means that they could go out of date when we upgrade to the next version of Lucene * The example code on the home page is missing details about what NuGet packages to reference, what namespaces to import, and a basic way to make the code run (#453) * There is also an external demo project, [LuceneNetDemo](https://github.com/NightOwl888/LuceneNetDemo) that is being kept up to date, but is not being referenced in documentation. Instructions on how to get it running are also pretty thin. The bottom line is that it is not easy to locate the demos and if you do find them there is little information about how to run them. ### Research We need to research to find the best way to get these demos running on developer machines and update the documentation and website to make this experience go smoother. I suspect we can use the [`dotnet new`](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-new) command in combination with `lucene-cli` and `dotnet run` to do most of the heavy lifting. But it also might make sense to use the templating feature of `dotnet new`. We should investigate how other open source projects are providing runnable demos to end users to see if there are any ideas we can borrow. It would also certainly be useful to run the Java demos to determine exactly how they are intended to be used. For Lucene.Net.Benchmarks, we have similar issues because it is unclear how the app is intended to be used by end users. So, what is learned about the demos will also help us work out how to create the optimal user experience for Lucene.Net.Benchmarks. * Like Lucene.Net.Demo, we compile Lucene.Net.Benchmarks into `lucene-cli`. * Lucene.Net.Benchmarks is not exportable as source code. * Unlike Lucene.Net.Demo, Lucene.Net.Benchmarks is compiled and distributed on NuGet. It is clear that Lucene.Net.Benchmark must be referenced to extend types, but the extensions need to be loaded via Reflection on the command line to run (#305). It is not clear if there was a workflow in Java where you are expected to compile from source to do the benchmarks, although it may also have been possible for end users to make their own runner implementation. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
