Mailing-List: contact dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@lucene.apache.org
Date: Wed, 28 Aug 2013 09:36:52 +0000 (UTC)
From: "Aleksandra Wozniak (JIRA)" <jira@apache.org>
To: dev@lucene.apache.org
Message-ID: <JIRA.12529670.1320158725791.45990.1377682612638@arcas>
In-Reply-To: <JIRA.12529670.1320158725791@arcas>
References: <JIRA.12529670.1320158725791@arcas>
Subject: [jira] [Updated] (LUCENE-3550) Create example code for core
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable


     [ https://issues.apache.org/jira/browse/LUCENE-3550?page=3Dcom.atlassi=
an.jira.plugin.system.issuetabpanels:all-tabpanel ]

Aleksandra Wozniak updated LUCENE-3550:
---------------------------------------

    Attachment: LUCENE-3550-sort.patch

Hi,

recently I started learning Lucene API and I along the way created a few sn=
ippets showing different Lucene features. I found this issue by coincidence=
 and I decided to rework one of them to fit into the examples implementatio=
n =E2=80=93 I'm sending a patch with my sort example + a corresponding unit=
 test.

Manpreet, I see that you started working on this issue a while ago =E2=80=
=93 I don't want to interfere with your work. You can incorporate my exampl=
e in your code or use it in any other way, if you find it useful.

Cheers,
Aleksandra
               =20
> 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
>         Attachments: LUCENE-3550.patch, LUCENE-3550-sort.patch
>
>
> 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 itse=
lf is documented, in addition to javadoc. Also, the code itself is being un=
it tested regularly.
> We found it very difficult to keep documentation up-to-date -- javadocs a=
lways 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 brea=
k the API, it fails to run if you change internal impl behavior. If you kee=
p it simple enough, its documentation stays simple to.
> And if we are successful at maintaining it (which we must be, otherwise t=
he 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 d=
ocuments which have the fields ID, date and body". Then you create an examp=
le class/method that accomplishes that. And between releases, this code get=
s updated, and people can follow the changes required to implement that sce=
nario.
> 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 a=
t least we can get it compiled and regularly unit tested.
> I think that it would be good if we introduce the concept of examples suc=
h that if a module (core, contrib, modules) have an src/examples, we packag=
e it in a .jar and include it with the binary distribution. That's for a fi=
rst step. We can also have meta examples, under their own module/contrib, t=
hat show how to combine several modules together (this might even uncover A=
PI 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 distribu=
te 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 administrato=
rs
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