Tika Changelog

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Tika Changelog

chrismattmann
Hi Guys,

 I've created a Tika changelog, CHANGES.txt, within the TIKA trunk that we
can use to track changes, akin to Nutch. Typically, when a committer commits
a patch (in Nutch) that closes out a tracked issue (i.e., with JIRA), then
we add a comment into CHANGES.txt, akin to the following (where "n" is a
number incremented from 1, for each release):

....

n+1. <issue key within JIRA> - <issue name within JIRA> (<committer
name>|<contributor name> via <committer name>)

....

(of course, without the "<" and ">" and "...." above). So, an example would
be TIKA-5. When I commit TIKA-5, I will add an entry to CHANGES.txt akin to:

....

1. TIKA-5 - Port Metadata Framework from Nutch (mattmann)

....

 Sound good?

Thanks!

Cheers,
  Chris



Reply | Threaded
Open this post in threaded view
|

Re: Tika Changelog

Jukka Zitting
Hi,

On 6/7/07, Chris Mattmann <[hidden email]> wrote:
> I've created a Tika changelog, CHANGES.txt, within the TIKA trunk that we
> can use to track changes, akin to Nutch. Typically, when a committer commits
> a patch (in Nutch) that closes out a tracked issue (i.e., with JIRA), then
> we add a comment into CHANGES.txt, akin to the following (where "n" is a
> number incremented from 1, for each release):
> [...]
> Sound good?

I think it's just duplicating information from the svn log, but if
people think it's a good idea, then I have no problem following suit.

BR,

Jukka Zitting
Reply | Threaded
Open this post in threaded view
|

Re: Tika Changelog

Sami Siren-2
2007/6/12, Jukka Zitting <[hidden email]>:

> Hi,
>
> On 6/7/07, Chris Mattmann <[hidden email]> wrote:
> > I've created a Tika changelog, CHANGES.txt, within the TIKA trunk that we
> > can use to track changes, akin to Nutch. Typically, when a committer commits
> > a patch (in Nutch) that closes out a tracked issue (i.e., with JIRA), then
> > we add a comment into CHANGES.txt, akin to the following (where "n" is a
> > number incremented from 1, for each release):
> > [...]
> > Sound good?
>
> I think it's just duplicating information from the svn log, but if
> people think it's a good idea, then I have no problem following suit.

Jira can also provide a list of changes (if all changes are logged
there) with the changelog - or release notes [1] functionality.

[1] http://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12312013&styleName=Text&projectId=10680&Create=Create

--
 Sami Siren
Reply | Threaded
Open this post in threaded view
|

Re: Tika Changelog

Yonik Seeley-2
On 6/12/07, Sami Siren <[hidden email]> wrote:

> 2007/6/12, Jukka Zitting <[hidden email]>:
> > On 6/7/07, Chris Mattmann <[hidden email]> wrote:
> > > I've created a Tika changelog, CHANGES.txt, within the TIKA trunk that we
> > > can use to track changes, akin to Nutch. Typically, when a committer commits
> > > a patch (in Nutch) that closes out a tracked issue (i.e., with JIRA), then
> > > we add a comment into CHANGES.txt, akin to the following (where "n" is a
> > > number incremented from 1, for each release):
> >
> > I think it's just duplicating information from the svn log, but if
> > people think it's a good idea, then I have no problem following suit.
>
> Jira can also provide a list of changes (if all changes are logged
> there) with the changelog - or release notes [1] functionality.
>
> [1] http://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12312013&styleName=Text&projectId=10680&Create=Create

I personally use CHANGES.txt in Lucene and Solr as user-level
documentation / release notes.  If it's too minor, an internal
cleanup, a documentation fix, etc, I don't put it in.  It also
provides a place to concisely explain the impact of a change (in user
language), rather than requiring the user to try and glean this from a
long JIRA discussion mingled with dev-list discissions.

Examples:

 3. SOLR-91: allow configuration of a limit of the number of searchers
    that can be warming in the background.  This can be used to avoid
    out-of-memory errors, or contention caused by more and more searchers
    warming in the background.  An error is thrown if the limit specified
    by maxWarmingSearchers in solrconfig.xml is exceeded. (yonik)

and

 3. LUCENE-710: added optional autoCommit boolean to IndexWriter
    constructors.  When this is false, index changes are not committed
    until the writer is closed.  This gives explicit control over when
    a reader will see the changes.  Also added optional custom
    deletion policy to explicitly control when prior commits are
    removed from the index.  This is intended to allow applications to
    share an index over NFS by customizing when prior commits are
    deleted. (Mike McCandless)

It's much more understandable then a JIRA bug list, but it does take more work.
If you wish to go this route, you could perhaps defer it until the
first Tika release.

-Yonik
Reply | Threaded
Open this post in threaded view
|

Re: Tika Changelog

chrismattmann
Hi Folks,

 My +1 for having a CHANGES.txt file, for all the reasons that Yonik
mentioned below. Also, it, to me, is much easier to maintain (simply doing
it incrementally, with each major update), then figuring out the mysteries
of JIRA ;)

 So, I'd like to call for a vote from the committer community. Should we use
a CHANGES.txt file? (please mark an X by your choice)

[ ]  Yes
[ ]  No

 Let's leave the vote open until we have a majority of binding votes.

Thanks!

Cheers,
  Chris





On 6/12/07 12:38 PM, "Yonik Seeley" <[hidden email]> wrote:

> On 6/12/07, Sami Siren <[hidden email]> wrote:
>> 2007/6/12, Jukka Zitting <[hidden email]>:
>>> On 6/7/07, Chris Mattmann <[hidden email]> wrote:
>>>> I've created a Tika changelog, CHANGES.txt, within the TIKA trunk that we
>>>> can use to track changes, akin to Nutch. Typically, when a committer
>>>> commits
>>>> a patch (in Nutch) that closes out a tracked issue (i.e., with JIRA), then
>>>> we add a comment into CHANGES.txt, akin to the following (where "n" is a
>>>> number incremented from 1, for each release):
>>>
>>> I think it's just duplicating information from the svn log, but if
>>> people think it's a good idea, then I have no problem following suit.
>>
>> Jira can also provide a list of changes (if all changes are logged
>> there) with the changelog - or release notes [1] functionality.
>>
>> [1]
>> http://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12312013&styleN
>> ame=Text&projectId=10680&Create=Create
>
> I personally use CHANGES.txt in Lucene and Solr as user-level
> documentation / release notes.  If it's too minor, an internal
> cleanup, a documentation fix, etc, I don't put it in.  It also
> provides a place to concisely explain the impact of a change (in user
> language), rather than requiring the user to try and glean this from a
> long JIRA discussion mingled with dev-list discissions.
>
> Examples:
>
>  3. SOLR-91: allow configuration of a limit of the number of searchers
>     that can be warming in the background.  This can be used to avoid
>     out-of-memory errors, or contention caused by more and more searchers
>     warming in the background.  An error is thrown if the limit specified
>     by maxWarmingSearchers in solrconfig.xml is exceeded. (yonik)
>
> and
>
>  3. LUCENE-710: added optional autoCommit boolean to IndexWriter
>     constructors.  When this is false, index changes are not committed
>     until the writer is closed.  This gives explicit control over when
>     a reader will see the changes.  Also added optional custom
>     deletion policy to explicitly control when prior commits are
>     removed from the index.  This is intended to allow applications to
>     share an index over NFS by customizing when prior commits are
>     deleted. (Mike McCandless)
>
> It's much more understandable then a JIRA bug list, but it does take more
> work.
> If you wish to go this route, you could perhaps defer it until the
> first Tika release.
>
> -Yonik


Reply | Threaded
Open this post in threaded view
|

Re: Tika Changelog

Doug Cutting
+1 for CHANGES.txt.  Yes, it is largely redundant with information in
Jira, but its advantages are [1] a more consise, user-friendly
description than usually exists in Jira (as illustrated by Yonik); and
[2] it provides a great sanity check when merging changes between
branches, since each commit is accompanied by a description.  You can
run 'svn merge ...' then 'svn diff CHANGES.txt' and easily check whether
the merge included the desired changes.

I think the best practice is to include a description of the change both
in CHANGES.txt and in the commit message.  The description in the commit
message might be shorter, e.g., only the first sentence from
CHANGES.txt.  Commit messages should of course also always include all
relevant Jira issue ids, whether it is the initial commit or a merge
between branches.  This is more redundancy, but descriptive commit
messages make it possible to use things 'svn log' without constantly
having to follow references to Jira, and issue ids in commit messages
make it possible to see in Jira all branches and revisions that a patch
is in.  These cost a bit at commit time, but make the repository and
Jira much nicer to use.

Doug


Chris Mattmann wrote:

> Hi Folks,
>
>  My +1 for having a CHANGES.txt file, for all the reasons that Yonik
> mentioned below. Also, it, to me, is much easier to maintain (simply doing
> it incrementally, with each major update), then figuring out the mysteries
> of JIRA ;)
>
>  So, I'd like to call for a vote from the committer community. Should we use
> a CHANGES.txt file? (please mark an X by your choice)
>
> [ ]  Yes
> [ ]  No
>
>  Let's leave the vote open until we have a majority of binding votes.
>
> Thanks!
>
> Cheers,
>   Chris
>
>
>
>
>
> On 6/12/07 12:38 PM, "Yonik Seeley" <[hidden email]> wrote:
>
>> On 6/12/07, Sami Siren <[hidden email]> wrote:
>>> 2007/6/12, Jukka Zitting <[hidden email]>:
>>>> On 6/7/07, Chris Mattmann <[hidden email]> wrote:
>>>>> I've created a Tika changelog, CHANGES.txt, within the TIKA trunk that we
>>>>> can use to track changes, akin to Nutch. Typically, when a committer
>>>>> commits
>>>>> a patch (in Nutch) that closes out a tracked issue (i.e., with JIRA), then
>>>>> we add a comment into CHANGES.txt, akin to the following (where "n" is a
>>>>> number incremented from 1, for each release):
>>>> I think it's just duplicating information from the svn log, but if
>>>> people think it's a good idea, then I have no problem following suit.
>>> Jira can also provide a list of changes (if all changes are logged
>>> there) with the changelog - or release notes [1] functionality.
>>>
>>> [1]
>>> http://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12312013&styleN
>>> ame=Text&projectId=10680&Create=Create
>> I personally use CHANGES.txt in Lucene and Solr as user-level
>> documentation / release notes.  If it's too minor, an internal
>> cleanup, a documentation fix, etc, I don't put it in.  It also
>> provides a place to concisely explain the impact of a change (in user
>> language), rather than requiring the user to try and glean this from a
>> long JIRA discussion mingled with dev-list discissions.
>>
>> Examples:
>>
>>  3. SOLR-91: allow configuration of a limit of the number of searchers
>>     that can be warming in the background.  This can be used to avoid
>>     out-of-memory errors, or contention caused by more and more searchers
>>     warming in the background.  An error is thrown if the limit specified
>>     by maxWarmingSearchers in solrconfig.xml is exceeded. (yonik)
>>
>> and
>>
>>  3. LUCENE-710: added optional autoCommit boolean to IndexWriter
>>     constructors.  When this is false, index changes are not committed
>>     until the writer is closed.  This gives explicit control over when
>>     a reader will see the changes.  Also added optional custom
>>     deletion policy to explicitly control when prior commits are
>>     removed from the index.  This is intended to allow applications to
>>     share an index over NFS by customizing when prior commits are
>>     deleted. (Mike McCandless)
>>
>> It's much more understandable then a JIRA bug list, but it does take more
>> work.
>> If you wish to go this route, you could perhaps defer it until the
>> first Tika release.
>>
>> -Yonik
>
>