Lucene - Core
  1. Lucene - Core
  2. LUCENE-3587

Attempting to link to Java SE JavaDocs is competely unreliable

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 3.6, 4.0-ALPHA
    • Component/s: None
    • Labels:
      None

      Description

      As noted several times since Oracle bought Sun, the canonical links to the Java SE JavaDocs have been unreliable and frequently cause warnings.

      Since we choose to fail the build on javadoc warnings, this is a serious problem for anyone trying to build from source if/when the package-list we reference in our common-build.xml is not available.

      We should eliminate this dependency.

      1. LUCENE-3587.trunk.patch
        1 kB
        Hoss Man
      2. LUCENE-3587.keep-javadoc-link.trunk.patch
        1 kB
        Steve Rowe
      3. LUCENE-3587.keep-javadoc-link.3x.patch
        1 kB
        Steve Rowe
      4. LUCENE-3587.3x.patch
        1 kB
        Hoss Man

        Issue Links

          Activity

          Hide
          Hoss Man added a comment -

          Patch against trunk demonstrating the change i suggest we make (to both trunk and 3x, and ideally the 3.5 release branch as well assuming we want to go with an RC3)

          This doesn't prevent us from continuing to use a local version of the package-list in our jenkins build, but since we can't ship that file in our releases, this is a good compromise that eliminates our dependency on a the flaky and ever changing URL for javadocs.

          Show
          Hoss Man added a comment - Patch against trunk demonstrating the change i suggest we make (to both trunk and 3x, and ideally the 3.5 release branch as well assuming we want to go with an RC3) This doesn't prevent us from continuing to use a local version of the package-list in our jenkins build, but since we can't ship that file in our releases, this is a good compromise that eliminates our dependency on a the flaky and ever changing URL for javadocs.
          Hide
          Hoss Man added a comment -

          equivalent patch for the 3x (and 3.5) branches.

          Show
          Hoss Man added a comment - equivalent patch for the 3x (and 3.5) branches.
          Hide
          Robert Muir added a comment -

          +1 to the patch (i think its the best solution), on the condition that the release process
          doesn't change... this means we won't have these links on the website.

          I don't want to make releases any harder so I don't think putting the burden on the RM to do something crazy to
          get those links on the website is worth it... for the most part lucene's classes extend other lucene classes
          or java.lang.Object so I don't think this is a bad compromise at all.

          Show
          Robert Muir added a comment - +1 to the patch (i think its the best solution), on the condition that the release process doesn't change... this means we won't have these links on the website. I don't want to make releases any harder so I don't think putting the burden on the RM to do something crazy to get those links on the website is worth it... for the most part lucene's classes extend other lucene classes or java.lang.Object so I don't think this is a bad compromise at all.
          Hide
          Steve Rowe added a comment -

          I think we should just stop failing the build for this particular warning. I'll work up a patch.

          Show
          Steve Rowe added a comment - I think we should just stop failing the build for this particular warning. I'll work up a patch.
          Hide
          Steve Rowe added a comment -

          Trunk & branch_3x versions of patch to ignore the package-list download warning.

          This way we at least attempt to do the right thing, but don't fail the build when Oracle fails to not suck.

          Show
          Steve Rowe added a comment - Trunk & branch_3x versions of patch to ignore the package-list download warning. This way we at least attempt to do the right thing, but don't fail the build when Oracle fails to not suck.
          Hide
          Robert Muir added a comment -

          Thanks for the alternative patch Steven.

          My question remains: what is the release process?

          If we are going to let this warning 'thru' but then the onus is on the RM to ensure
          that these links are in fact actually working for release candidate builds etc,
          then I'm against the patch, because its a step backwards from releasing (back to
          manual inspections of everything).

          Show
          Robert Muir added a comment - Thanks for the alternative patch Steven. My question remains: what is the release process? If we are going to let this warning 'thru' but then the onus is on the RM to ensure that these links are in fact actually working for release candidate builds etc, then I'm against the patch, because its a step backwards from releasing (back to manual inspections of everything).
          Hide
          Hoss Man added a comment -

          rmuir: I'm not sure where/how you got the impression that anything about the release process should change. If someone intended that, they should have said so yes/no?

          Personally i'd prefer my patch to sarowe's, because then the generated javadocs don't change depending on if/when the oracle URL is up. In general I disagree with sarowe's comment that ignoring the warning would mean we "attempt to do the right thing" – because that implies that linking to the oracle.com URL is "the right thing" ... i think we should move away from that thinking. In my opinion "the right thing" is to build our own docs and not make assumptions about external docs. If the end user wants to build docs that hyperlink to oracle.com (or my.company.com/javadocs) that can be their choice, and if the URL is down and the linkage fails then the build.xml should fail to generate the docs because it couldn't do what the user asked it to.

          but honestly: either patch is better then what we've got now.

          Show
          Hoss Man added a comment - rmuir: I'm not sure where/how you got the impression that anything about the release process should change. If someone intended that, they should have said so yes/no? Personally i'd prefer my patch to sarowe's, because then the generated javadocs don't change depending on if/when the oracle URL is up. In general I disagree with sarowe's comment that ignoring the warning would mean we "attempt to do the right thing" – because that implies that linking to the oracle.com URL is "the right thing" ... i think we should move away from that thinking. In my opinion "the right thing" is to build our own docs and not make assumptions about external docs. If the end user wants to build docs that hyperlink to oracle.com (or my.company.com/javadocs) that can be their choice, and if the URL is down and the linkage fails then the build.xml should fail to generate the docs because it couldn't do what the user asked it to. but honestly: either patch is better then what we've got now.
          Hide
          Steve Rowe added a comment -

          Hoss, whatever happened to LUCENE-3228 ?

          Show
          Steve Rowe added a comment - Hoss, whatever happened to LUCENE-3228 ?
          Hide
          Jason Rutherglen added a comment -

          +1 on the patch. Javadoc external links should not destroy a build.

          Show
          Jason Rutherglen added a comment - +1 on the patch. Javadoc external links should not destroy a build.
          Hide
          Steve Rowe added a comment -

          LUCENE-3228 addresses this issue by maintaining local copies of external package-list files.

          Show
          Steve Rowe added a comment - LUCENE-3228 addresses this issue by maintaining local copies of external package-list files.

            People

            • Assignee:
              Steve Rowe
              Reporter:
              Hoss Man
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development