Old links to docs are broken

[filiph]

URL: https://pub.dev/documentation/http/0.11.3+16/http/BaseRequest-class.html

At some point in the past, the URL above worked (I used it here on StackOverflow. Now it's a 404.

The latest documentation does work on an analogous URL: https://pub.dev/documentation/http/latest/http/BaseRequest-class.html. So it seems this is just a case of old documentation being deleted after a while?

I realize keeping docs for every version of every package takes resources. On the other hand, the only reliable way to link to some docs of some package is to pin the version — so that later changes to the API don't break the intent of the link (e.g. linking to a class whose API has changed significantly, or that was removed).

I'll leave it to the maintainers of pub.dev to decide whether the increased resources (mainly space, I reckon) are worth fixing this issue. Just wanted to raise the issue in case it's not known.

[sigurdm]

I think more than space, it is a matter of us wanting to regenerate the docs with the current dart doc, and https://pub.dev/packages/http/versions/0.11.3+16 is not dart 2 compatible.

We could somehow retain old generated docs where we no longer are able/willing to generate new - but they would not benefit from eg. redesigns or protection from XSS-attacks or whatever else improvements we make to dartdoc.

[sigurdm]

Maybe we could give a better 404 telling that the package is too old for us to generate dartdoc for, and point to the current dartdoc.

[isoos]

I think we would like to keep the pub.dev site's "evergreen" approach as much as possible, e.g. always reflecting on the package statuses what they look like with the latest stable tooling. Unfortunately it means that we will drop analysis or documentation from versions that are not up-to-date.

Having said that, I think it may be worth considering to support (1) the latest version of a package (2) that has active use (3) with the SDK that it claims to support, even if it is not the canonical SDK we are using. Right now the analysis instances are not setup for that, but I think this will be easier to implement with the new sandboxing model, if the SDKs are downloaded dynamically - we could prepare the analysis payload to also include the specific version that we want to use.

In the first iteration I think it would mean that we don't keep the documentation, but re-create it on each new cycle - pending that the latest version of the old package is still in use. That would keep the cleanup logic clear of complexities and we can use the runtime-based approach.

Note: this is more useful for documentation, and less for pana, because I think we want to keep using the latest pana rules, which may cause low points for old/outdated packages. However, low points may be better than no points at all...

[filiph]

Agree on both points. At least a better 404 would be excellent, something like:

This version's documentation wasn't retained because the version is not up to date with the latest Dart. Click here to get the latest version of this package.

And yes, it would be fantastic to get a proper documentation even for old packages, but I'd say it's not high priority.

[isoos]

Recently we've discussed that with the new sandboxing model, we will have a good automatic redirect mechanism, e.g. 1.2.2 -> 1.2.5 in case the 1.2.5 is the latest. Most part of the redirection/caching/canonical links is already implemented, but we need to implement the 1.2.2->1.2.5 rules.

[StephenWithPH]

pub.dev's behavior of immediately removing out-of-date package documentation intersects painfully with dart doc's version pinning in generated links.

In the sample below, Dart doc will generate a link to https://pub.dev/documentation/firebase_auth/<VERSION>/firebase_auth/FirebaseAuthException-class.html, where <VERSION> is the fully-qualified semver from pubspec.lock.

import 'package:firebase_auth/firebase_auth.dart';

class MyClass {

  /// May throw a [FirebaseAuthException].
  Future<void> doStuff() {
    // ...
  }

}

As soon as a new version of a package is published, previously-generated dart doc docs are now broken, because https://pub.dev/documentation/firebase_auth/4.11.0/firebase_auth/FirebaseAuthException-class.html no longer resolves (https://pub.dev/documentation/firebase_auth/4.11.1/firebase_auth/FirebaseAuthException-class.html does... for now).

It would make for a much smoother dev experience if older versions of package docs were kept around to preserve links with pinned versions generated by dart doc.

[StephenWithPH]

Most part of the redirection/caching/canonical links is already implemented, but we need to implement the 1.2.2->1.2.5 rules.

This would go a long way in solving the problem. Assuming dart doc could (in the future) validate links (see dart-lang/dartdoc#3543), the remaining broken links would be tolerable (and a very subtle indicator that your dependencies are going to break you upon upgrade).

[isoos]

Closing this as it has been fixed and deployed a few weeks ago:
https://pub.dev/documentation/firebase_auth/4.11.0/firebase_auth/FirebaseAuthException-class.html now resolves to the 4.14.0 version: https://pub.dev/documentation/firebase_auth/4.14.0/firebase_auth/FirebaseAuthException-class.html