Site-www: Document `pub outdated` at https://dart.dev/tools/pub/cmd/pub-outdated

[sigurdm]

New command being developed here: https://github.com/dart-lang/pub/pull/2315.

This should be done before next stable sdk release

[kwalrath]

I'm starting now, so let me know if there's anything non-obvious I should know, @sigurdm. Otherwise, expect to hear from me when I have a PR.

[sigurdm]

The command itself claims to be documented at: https://dart.dev/tools/pub/cmd/pub-outdated it would be nice if that could be the real url :)

I know @mit-mit has written a bit about pub outdated in an internal document. Maybe it contains some useful details.

I'll also give you access to our original design doc.

[kwalrath]

Along with the doc of pub outdated, we should document best practices for dependency management, which is probably a more invasive change. (A first draft of the proposed content is below.) Also, we should search for references to pub upgrade, and consider adding a reference to pub outdated and/or best practices.

Here's some best practice text we can start with:

Specifying your dependencies

Overall, Dart dependencies come in three kinds:

1. _Regular dependencies_: The main dependencies of your app or package, listed under the dependencies key in your pubspec.yaml file.
2. _Dev dependencies_: Additional dependencies used during development of a package, for example when running tests, or to run a code generator.
3. _Transitive dependencies_: Additional dependencies that either a regular or dev dependency transitively depend on.

As a developer you specify your regular and dev dependencies in your app or package pubspec.yaml file. These dependency declarations include version constraints, for example this dependency on path which uses the pub caret syntax to specify that the app is compatible with any version of path that is higher than or equal to 1.6.3, and lower than 2.0.0 (>=1.6.3, <2.0.0):

dependencies:
  path: ^1.6.3

Specifying dependencies with such version ranges is considered a good practice as it allows the pub tool to select newer versions of the package when they become available. Also, it places an upper limit on the allowed version based on an assumption that packages are versioning using semantic versions, where any version of path versioned 1.x is compatible, but where a new version 2.x would be a major upgrade, not semantically compatible with the 1.x versions.

Resolving versions

When you run the pub get command, the pub version solver (aka PubGrub) runs a process to determine the latest possible set of versions of all your dependencies (regular, dev, and transitive) that combined satisfies the constraints listed by each and every dependency. Note that pub uses a single-version scheme where each package is included in a single-version-only in your app; this is an important optimization to ensure that your app size is kept as small as possible.

This also highlights an important point: Should any of your dependencies be stale — for example, consider a case where you have specified a restrictive dependency on path: 1.4.0 — then you end up with not only a stale version of that single package, but potentially also with stale versions of any other package in your dependency graph that indirectly depends on path. This can have a negative impact on the stability, performance, and quality of your app, so it’s important that you actively manage your dependencies and ensure you are on the freshest versions possible.

[sigurdm]

Best practices might be a good idea.

A few minor suggestions:

Transitive dependencies: Additional dependencies that either a regular and/or dev dependency transitively depend on.

, the pub version solver (aka PubGrub)

Very much a nit, but I believe the algorithm is called PubGrub, and the solver implements that algorithm. Maybe we can write

the pub version solver runs a resolution (using the PubGrub algorithm) to determine...

In the last paragraph it seems natural to link to the pub outdated doc as a tool for keeping the dependencies up-to-date.

Somehow I feel that 'best practices' should repeat https://dart.dev/tools/pub/glossary#lockfile about when to check in your pubspec.lock and when not to.