: 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
