Mailing-List: contact solr-dev-help@lucene.apache.org; run by ezmlm
Precedence: bulk
Reply-To: solr-dev@lucene.apache.org
Received-SPF: neutral (herse.apache.org: local policy)
Date: Mon, 9 Jul 2007 11:32:15 -0700 (PDT)
From: Chris Hostetter <hossman_lucene@fucit.org>
To: solr-dev@lucene.apache.org
Subject: Re: what goes in CHANGES.txt
In-Reply-To: <c68e39170707091111w420b2d34i35b218bc74586915@mail.gmail.com>
Message-ID: <Pine.LNX.4.58.0707091123190.21312@hal.rescomp.berkeley.edu>
References: <c68e39170707090833x6aa29a33j6923c8010f4d2950@mail.gmail.com>
 <Pine.LNX.4.58.0707091051440.21312@hal.rescomp.berkeley.edu>
 <c68e39170707091111w420b2d34i35b218bc74586915@mail.gmail.com>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII


: 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