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