[
https://issues.apache.org/jira/browse/LUCENE-3550?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13564326#comment-13564326
]
Shai Erera commented on LUCENE-3550:
------------------------------------
Hi Mandy. The basic idea behind this issue was to create some example code
which demonstrates different scenarios of indexing with Lucene. With Lucene 4.0
came many changes to the API and such example code was badly missing (luckily,
there was good migration document).
The facets module has such example code which:
* Ensures that when the API changes, the code is updated -- it's like live
documentation of the code, which we must update in order for it to compile
* Tested regularly, so that it not only compiles, but also works :).
At the time I thought that it would be good to follow that practice for Lucene
core, ensuring that when APIs change / features removed, we update the
corresponding example code on one hand, but also have the chance to evaluate
the change, against real code.
Lucene has a 'demo' module, so we should put the examples code under it. Let's
start by defining some use cases that we'd like to demo, e.g.:
* SimpleExample: index few fields into few documents and offer index() and
search() methods, that index the content, as well as search some stuff.
** A corresponding test should e.g. run some queries against the result index
and validate that things were indexed properly.
* SortExample: same as above, but indexes some fields for sorting purposes,
using e.g. DocValues and whatever else we can sort on.
** And again, a corresponding test.
* NumericExample: index few numeric fields and demo range queries etc.
** Plus a corresponding test.
Let's start with these, and then we can build more.
> Create example code for core
> ----------------------------
>
> Key: LUCENE-3550
> URL: https://issues.apache.org/jira/browse/LUCENE-3550
> Project: Lucene - Core
> Issue Type: New Feature
> Components: core/other
> Reporter: Shai Erera
> Labels: newdev
> Fix For: 4.2, 5.0
>
>
> Trunk has gone under lots of API changes. Some of which are not trivial, and
> the migration path from 3.x to 4.0 seems hard. I'd like to propose some way
> to tackle this, by means of live example code.
> The facet module implements this approach. There is live Java code under
> src/examples that demonstrate some well documented scenarios. The code itself
> is documented, in addition to javadoc. Also, the code itself is being unit
> tested regularly.
> We found it very difficult to keep documentation up-to-date -- javadocs
> always lag behind, Wiki pages get old etc. However, when you have live Java
> code, you're *forced* to keep it up-to-date. It doesn't compile if you break
> the API, it fails to run if you change internal impl behavior. If you keep it
> simple enough, its documentation stays simple to.
> And if we are successful at maintaining it (which we must be, otherwise the
> build should fail), then people should have an easy experience migrating
> between releases. So say you take the simple scenario "I'd like to index
> documents which have the fields ID, date and body". Then you create an
> example class/method that accomplishes that. And between releases, this code
> gets updated, and people can follow the changes required to implement that
> scenario.
> I'm not saying the examples code should always stay optimized. We can aim at
> that, but I don't try to fool myself thinking that we'll succeed. But at
> least we can get it compiled and regularly unit tested.
> I think that it would be good if we introduce the concept of examples such
> that if a module (core, contrib, modules) have an src/examples, we package it
> in a .jar and include it with the binary distribution. That's for a first
> step. We can also have meta examples, under their own module/contrib, that
> show how to combine several modules together (this might even uncover API
> problems), but that's definitely a second phase.
> At first, let's do the "unit examples" (ala unit tests) and better start with
> core. Whatever we succeed at writing for 4.0 will only help users. So let's
> use this issue to:
> # List example scenarios that we want to demonstrate for core
> # Building the infrastructure in our build system to package and distribute a
> module's examples.
> Please feel free to list here example scenarios that come to mind. We can
> then track what's been done and what's not. The more we do the better.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
