lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steven Rowe (Commented) (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (LUCENE-3550) Create example code for core
Date Tue, 01 Nov 2011 14:55:32 GMT

    [ https://issues.apache.org/jira/browse/LUCENE-3550?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13141215#comment-13141215
] 

Steven Rowe commented on LUCENE-3550:
-------------------------------------

+1

{{lucene/contrib/demo/}} is an existing lucene-core example, and should be folded into this
effort.

About release jar naming: we could call them lucene-<module>-example, e.g. lucene-core-example-X.Y.jar,
lucene-facet-example-X.Y.jar, etc.




                
> 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: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message