Create example code for core
----------------------------
Key: LUCENE-3550
URL: https://issues.apache.org/jira/browse/LUCENE-3550
Project: Lucene - Java
Issue Type: New Feature
Components: core/other
Reporter: Shai Erera
Fix For: 4.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:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
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]
