lucenenet-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From GitBox <...@apache.org>
Subject [GitHub] [lucenenet] NightOwl888 opened a new issue #457: Task: Optimize and Document End-to-End Demo and Benchmark Experience
Date Tue, 30 Mar 2021 10:11:44 GMT

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:
users@infra.apache.org



Mime
View raw message