Details

    • Type: Task Task
    • Status: Closed
    • Priority: Trivial Trivial
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.9.2, 3.0, 4.0-ALPHA
    • Component/s: general/javadocs
    • Labels:
      None
    • Lucene Fields:
      New, Patch Available

      Description

      In my opinion, we should elaborate more on the effects of changing the Version parameter.
      Particularly, changing this value, even if you recompile your code, likely involves reindexing your data.
      I do not think this is adequately clear from the current javadocs.

      1. LUCENE-2080.patch
        2 kB
        Robert Muir
      2. LUCENE-2080.patch
        2 kB
        Robert Muir
      3. LUCENE-2080.patch
        1 kB
        Robert Muir
      4. LUCENE-2080.patch
        0.6 kB
        Robert Muir

        Activity

        Hide
        Robert Muir added a comment -

        here is an initial patch to try to improve it.

        Show
        Robert Muir added a comment - here is an initial patch to try to improve it.
        Hide
        Michael McCandless added a comment -

        +1

        Show
        Michael McCandless added a comment - +1
        Hide
        Robert Muir added a comment -

        Uwe, maybe we could have some very very short verbage about this in 3.0 release notes, since it won't make 3.0?

        Show
        Robert Muir added a comment - Uwe, maybe we could have some very very short verbage about this in 3.0 release notes, since it won't make 3.0?
        Hide
        Uwe Schindler added a comment -

        +1, commit it to 3.0, too

        Its only documentation change, no need for a new RC because of this.

        Show
        Uwe Schindler added a comment - +1, commit it to 3.0, too Its only documentation change, no need for a new RC because of this.
        Hide
        Robert Muir added a comment -

        Committed revision 881819.

        Show
        Robert Muir added a comment - Committed revision 881819.
        Hide
        Robert Muir added a comment -

        I am reopening this, because I have noticed lots of usage of LUCENE_CURRENT on the user list, etc in examples from peoples code.
        So I would like to backport this to 2.9 branch.

        I think it may be the case that even with this warning, it is not enough. We should think of further improvements.

        Show
        Robert Muir added a comment - I am reopening this, because I have noticed lots of usage of LUCENE_CURRENT on the user list, etc in examples from peoples code. So I would like to backport this to 2.9 branch. I think it may be the case that even with this warning, it is not enough. We should think of further improvements.
        Hide
        Michael McCandless added a comment -

        +1 to fix on 2.9.x

        Show
        Michael McCandless added a comment - +1 to fix on 2.9.x
        Hide
        Robert Muir added a comment -

        It seems that LUCENE_CURRENT is still causing some confusion.

        I am reopening this issue and propose removing this constant entirely.

        Regardless of whether we want to remove it, it should be @deprecated, have much scarier javadocs text, and instead positive wording like 'latest and greatest' should instead be applied to LUCENE_31 (whatever the latest constant is), to encourage users to use that instead.

        Show
        Robert Muir added a comment - It seems that LUCENE_CURRENT is still causing some confusion. I am reopening this issue and propose removing this constant entirely. Regardless of whether we want to remove it, it should be @deprecated, have much scarier javadocs text, and instead positive wording like 'latest and greatest' should instead be applied to LUCENE_31 (whatever the latest constant is), to encourage users to use that instead.
        Hide
        Robert Muir added a comment -

        attached is a patch that deprecates LUCENE_CURRENT, adds some scarier text about 'reindexing all your documents', and moves positive 'latest & greatest' text to LUCENE_31 instead.

        Show
        Robert Muir added a comment - attached is a patch that deprecates LUCENE_CURRENT, adds some scarier text about 'reindexing all your documents', and moves positive 'latest & greatest' text to LUCENE_31 instead.
        Hide
        Robert Muir added a comment -

        I think this wording is even better and scarier:

        • i bolded re-index all your documents in the previous wording.
        • i added another sentence: Additionally, you may need to re-test your entire application to ensure it now does what you want, as some defaults may have changed and may break functionality in your application.
        Show
        Robert Muir added a comment - I think this wording is even better and scarier: i bolded re-index all your documents in the previous wording. i added another sentence: Additionally, you may need to re-test your entire application to ensure it now does what you want, as some defaults may have changed and may break functionality in your application.
        Hide
        Simon Willnauer added a comment -

        I like this extension and I think it is important! Yet, I would use the following wording instead:

        Additionally, you may need to re-test your entire application to ensure it behaves like expected, as some defaults may have changed and may break functionality in your application.

        Show
        Simon Willnauer added a comment - I like this extension and I think it is important! Yet, I would use the following wording instead: Additionally, you may need to re-test your entire application to ensure it behaves like expected, as some defaults may have changed and may break functionality in your application.
        Hide
        Michael McCandless added a comment -

        I like the new scary javadoc Robert! I think removing (deprecating today) LUCENE_CURRENT may make sense – it's very dangerous.

        Show
        Michael McCandless added a comment - I like the new scary javadoc Robert! I think removing (deprecating today) LUCENE_CURRENT may make sense – it's very dangerous.
        Hide
        Robert Muir added a comment -

        I was thinking... this wording could be more concise too. I will add simons suggestion, trying to also think of the scariest, shortest verbage we can use.

        Show
        Robert Muir added a comment - I was thinking... this wording could be more concise too. I will add simons suggestion, trying to also think of the scariest, shortest verbage we can use.
        Hide
        Robert Muir added a comment -

        updated patch with simon's suggestion, some reformatting and edits to be slightly scarier.

        if no one objects, will commit tomorrow (and backport, adjusting the 'latest and greatest' wordage to the appropriate versions)

        Show
        Robert Muir added a comment - updated patch with simon's suggestion, some reformatting and edits to be slightly scarier. if no one objects, will commit tomorrow (and backport, adjusting the 'latest and greatest' wordage to the appropriate versions)
        Hide
        Robert Muir added a comment -

        Committed revision 908975.

        Show
        Robert Muir added a comment - Committed revision 908975.
        Hide
        Uwe Schindler added a comment -

        We should add a note in CHANGES.txt in 3.0 and 2.9 branch as this is an API change.

        Something like: "Deprecated Version.LUCENE_CURRENT constant..." with the reason phrases from above

        Show
        Uwe Schindler added a comment - We should add a note in CHANGES.txt in 3.0 and 2.9 branch as this is an API change. Something like: "Deprecated Version.LUCENE_CURRENT constant..." with the reason phrases from above

          People

          • Assignee:
            Robert Muir
            Reporter:
            Robert Muir
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development