[
https://issues.apache.org/jira/browse/LUCENE-5125?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13713874#comment-13713874
]
Robert Muir commented on LUCENE-5125:
-------------------------------------
{quote}
Perhaps by following some advice they got from a blog or mailing list that
suggested they try docValuesFormat="Disk" w/o repeating the caveat?
I'm not trying to re-hash LUCENE-5121 – i'm just trying to ensure that we cover
all our bases in better documenting what codecs will and won't automatically
work on upgrade.
{quote}
Sorry I don't buy it. Its absolutely clear if you read all the comments on the
issue.
> Codec classes/packages that do not provide (automatic) file format back
> compat need to be more explicit about this in javadocs
> ------------------------------------------------------------------------------------------------------------------------------
>
> Key: LUCENE-5125
> URL: https://issues.apache.org/jira/browse/LUCENE-5125
> Project: Lucene - Core
> Issue Type: Improvement
> Reporter: Hoss Man
>
> rmuir noted in LUCENE-5121...
> bq. Currently (as documented), we don't provide index back compat for
> experimental codecs in lucene-codecs.jar.
> ...but except for a solr wiki page and solrconfig.xml comment, it's extremely
> non-obvious that any of these codec classes don't provide index backcompat.
> * the codec module overview.html page describes the module as "Collection of
> useful codec, postings format and terms dictionary implementations" -- with
> no indication that by using these "useful" implementations, the user gives up
> index backcompat.
> * the package.html files in the individual packages of the codec module
> (appending, blockterms, bbloom, diskdv, etc...) also say nothing about index
> backcompat
> * the individual classes in these codecs are mostly labeled with
> {{@lucene.experimental}} but in the resulting javadoc that merely says that
> "WARNING: This _API_ is experimental and might change in incompatible ways in
> the next release". Lots of classes in Lucene have this warning on them about
> their API (including the abstract codec apis themselves in lucene-core:
> DocValuesFormat, PostingsFormat, etc...) and that annotation (as far back as
> i can remember) has always only refered to the java API of the labeled class
> -- never to whether using that class ment you were giving up on index format
> back compat.
> Given how much effort and work is put into ensuring good index backcompat for
> default codec, we should be extremely explicit when/if alternative codecs do
> not support backcompat, so we don't frustrate/confuse users and leave them
> with the impression that they can never count on index backcompat just
> because they may not realize they were using an "unsupported" format option
> because of a blog post they read or advice they got on the mailing list about
> how to make something faster or use less ram.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
