what goes in CHANGES.txt

[Yonik Seeley <yo...@apache.org>]

I was browsing recent changes to CHANGES.txt, and some of them seem
perhaps a bit low-level to be there.  Here's my view:
http://www.nabble.com/Re%3A-Tika-Changelog-p11082404.html

IMO, changes in implementation detail don't belong in CHANGES.txt,
unless it's to give credit to a contributor for that change (which
committers don't need).

For example, the following change shouldn't matter to normal users:
SOLR-262: Added toObject( Fieldable ) to FieldType. [...]

-Yonik

Re: what goes in CHANGES.txt

[Yonik Seeley <yo...@apache.org>]

On 7/9/07, Walter Underwood <wu...@netflix.com> wrote:
> > : If we added a more obscure method that didn't exist before (like
> > : getFirstMatch()), that wouldn't need to be added (it's noise to most
> > : users, doesn't change existing functionality, not accessible w/o
> > : writing Java code, and an advanced user can pull up the javadoc).
>
> It sure is handy to know what release that first appeared if you
> are trying to work with an older version. --wunder

Our subversion repository is open, and nicely records all the changes.
We should try to avoid burying the average user in too many details.

-Yonik

Re: what goes in CHANGES.txt

[Walter Underwood <wu...@netflix.com>]

> : If we added a more obscure method that didn't exist before (like
> : getFirstMatch()), that wouldn't need to be added (it's noise to most
> : users, doesn't change existing functionality, not accessible w/o
> : writing Java code, and an advanced user can pull up the javadoc).

It sure is handy to know what release that first appeared if you
are trying to work with an older version. --wunder

Re: what goes in CHANGES.txt

[Chris Hostetter <ho...@fucit.org>]

: I disagree that it needs to be in CHANGES.txt... advanced expert users
: will also use the source/javadoc (and creating ones own field types is
: definitely advanced).  Every public class and method in solr isn't
: equally part of the "public" API.

true, but classes like FieldType are specificly noted as extension
points...
http://wiki.apache.org/solr/SolrPlugins

...in general, any situatuation where we support dynamic loading of
class/interface impls is a situation where changes to that class/interface
should be documented in the CHANGES.txt because it affets people providing
their own impl ... new methods on abstract base classes are particularly
important because people upgrading won't notice any compilation errors,
and may then wonder why some features (which may have worked in the past)
no longer work with their custom class.

the FieldType.toObject example is a perfect case of this ... without
drawing atention to the fact that it was added to support "updateable"
documents people with their own custom FieldTypes might get really
confused as to why updating docs doesn't work for them

: If we added a more obscure method that didn't exist before (like
: getFirstMatch()), that wouldn't need to be added (it's noise to most
: users, doesn't change existing functionality, not accessible w/o
: writing Java code, and an advanced user can pull up the javadoc).

I agree ... but only because SOlrIndexSearcher isn't a class we expect
advanced users to subclass so providing a new impl that they dont' know
about doesn't affect them ... but in cases like
FieldType, RequestHandlerBase, or BaseTokenFilterFactory, etc.... then new
methods added to those classes that other parts of Solr rely on for new
functionality (or a new methodology for previously existing functionality)
should be documented someplace advanced users can find them without
needing to diff the javadocs between releases.




-Hoss

Re: what goes in CHANGES.txt

[Yonik Seeley <yo...@apache.org>]

On 7/9/07, Chris Hostetter <ho...@fucit.org> wrote:
> : http://www.nabble.com/Re%3A-Tika-Changelog-p11082404.html
> :
> : IMO, changes in implementation detail don't belong in CHANGES.txt,
> : unless it's to give credit to a contributor for that change (which
> : committers don't need).
> :
> : For example, the following change shouldn't matter to normal users:
> : SOLR-262: Added toObject( Fieldable ) to FieldType. [...]
>
> i agree with teh sentiments you posted to the tika list, but we have to
> keep in mind that the scope of "users" is broad ... that note about
> SOLR-262 may not be important to users that only deal with Solr out of the
> box, but it is important to advanced users writing their own plugins --
> and should be noted in teh CHANGES.txt somewhere

I disagree that it needs to be in CHANGES.txt... advanced expert users
will also use the source/javadoc (and creating ones own field types is
definitely advanced).  Every public class and method in solr isn't
equally part of the "public" API.

It's somewhat subjective, but if we changed the semantics of something
like IndexSearcher.getDocList(), that should definitely be in
CHANGES.txt
If we added a more obscure method that didn't exist before (like
getFirstMatch()), that wouldn't need to be added (it's noise to most
users, doesn't change existing functionality, not accessible w/o
writing Java code, and an advanced user can pull up the javadoc).

> ... but i would agree
> that the "New Features" section probably isn't the right place for it.

Yes, either "other" or a new "java API" section

-Yonik

Re: what goes in CHANGES.txt

[Chris Hostetter <ho...@fucit.org>]

: http://www.nabble.com/Re%3A-Tika-Changelog-p11082404.html
:
: IMO, changes in implementation detail don't belong in CHANGES.txt,
: unless it's to give credit to a contributor for that change (which
: committers don't need).
:
: For example, the following change shouldn't matter to normal users:
: SOLR-262: Added toObject( Fieldable ) to FieldType. [...]

i agree with teh sentiments you posted to the tika list, but we have to
keep in mind that the scope of "users" is broad ... that note about
SOLR-262 may not be important to users that only deal with Solr out of the
box, but it is important to advanced users writing their own plugins --
and should be noted in teh CHANGES.txt somewhere ... but i would agree
that the "New Features" section probably isn't the right place for it.

this seems like a perfect example of the type of thing that belongs in
"Other Changes" ... or perhaps a new section in CHANGES specificly for
plugin developers.  ("Internal Changes" maybe?)


-Hoss

Re: what goes in CHANGES.txt

[Yonik Seeley <yo...@apache.org>]

On 7/9/07, Ryan McKinley <ry...@gmail.com> wrote:
> > IMO, changes in implementation detail don't belong in CHANGES.txt,
> > unless it's to give credit to a contributor for that change (which
> > committers don't need).
> >
>
> With SOLR-292, it seems confusing to list a bug fix for something added
> since the last release.  But since it is from a new/useful contributor I
> put it in.  Is that in line with your thoughts?

Yes.

-Yonik

Re: what goes in CHANGES.txt

[Ryan McKinley <ry...@gmail.com>]

> 
> IMO, changes in implementation detail don't belong in CHANGES.txt,
> unless it's to give credit to a contributor for that change (which
> committers don't need).
>

With SOLR-292, it seems confusing to list a bug fix for something added 
since the last release.  But since it is from a new/useful contributor I 
put it in.  Is that in line with your thoughts?

> For example, the following change shouldn't matter to normal users:
> SOLR-262: Added toObject( Fieldable ) to FieldType. [...]
> 

I'll remove SOLR-262