[2.19] More pub (maybe)

[MaryaBelanger]

This is an evaluation issue

Evaluating the potential need for documentation updates based on pub related items added to the change log late in the release cycle (bullets below)

Summary

The major points are being covered by 4514. This issue is just to make sure I double check dart.dev for everything else, though it's unlikely there's any significant change.

Evaluation

• dart pub add foo:<constraint> with an existing dependency will now update the constraint rather than fail.

  • in work: [2.19] Document new 'dart pub add' source and constraint syntax #4514

• dart pub add will now allow adding multiple packages from any source using the same YAML syntax as in pubspec.yaml.

  • in work: [2.19] Document new 'dart pub add' source and constraint syntax #4514

• Update dart pub publish to allow dependency_overrides in pubspec.yaml. They will still cause a publication warning. Note that only dependency_overrides from the root package effect resolution.

• Update dart pub publish to require a working resolution. If publishing a breaking release of mutually dependent packages use dependency_overrides to obtain a resolution.

• dart pub publish will now give a warning if dart analyze reports any diagnostics.

• dart pub publish now shows the file sizes of large files in your package to prevent accidental publication of large unrelated files.

• Fix a bug in dart pub upgrade --major-versions where packages not requiring major updates would be held back unless needed.

• dart pub get now fails gracefully when run from inside the pub-cache

[MaryaBelanger]

I didn't find anywhere in the docs that these points would be valuable to elaborate on.

The changes related to warnings and failures sufficiently sum up what's going on in their messages, so there doesn't need to be extra documentation to explain those.

E.g. for "dart pub get now fails gracefully when run from inside the pub-cache", the message the user will see is "Cannot operate on packages inside the cache.", kind of obvious to just get out of the cache to fix it.

---

Side note for future me:
This was the first time digging into pub developments that don't have corresponding issues in GH. I only found out about these changes from the change log, and none of them are linked to anything for more explanation.

It took me a while to figure out how to backtrack from the change log to find a source for more info. It seems simple now, but just in case, I'm writing it down for next time. Here's what to do:

• Go to the change log blame
• Click on the commit adjacent to the change log update
  • e.g. this one for the publish / analyze thing
  • takes you here
• Read the commit messages in the log on that page to find what you're looking for (e.g. this line highlighted) ** (or skip to last bullet)
  • click on the dart.googlesource... link to the right of the log entry
  • not the issue number link on the left, those seem to be unrelated? I'm not sure (e.g. this one isn't about publish?)
  • that will bring you to a page that lists all the files that were changed at the top
  • you can click through the files and ctrl+f search for the info you're looking for
• ** If none of those messages seem related to what you're looking for, just click on the long Diff: link below them and that'll show you all the changes
  • in the diff just ctrl+f phrases for what you're looking for
  • I searched "analyze" and found validator/analyze.dart file had the work I was looking for

[parlough]

@MaryaBelanger Thanks for completing this evaluation, everything make sense!

As for your process, sounds like you found one that works well for you :D

My personal process for pub (and other external repositories like dartdoc, test, dart_style, etc.) is similar to the following if it helps.

Pretend I want to compare what is on the current stable (2.19.0) to current dev/alpha (3.0.0-<v>-dev) for documenting the next release:

1. Open the base (stable) branch DEPS file: https://github.com/dart-lang/sdk/blob/stable/DEPS
2. Find the pub_rev in there: https://github.com/dart-lang/sdk/blob/stable/DEPS#L155
3. Open the target (dev) branch DEPS file: https://github.com/dart-lang/sdk/blob/dev/DEPS
4. Find the pub_rev in there: https://github.com/dart-lang/sdk/blob/dev/DEPS#L159
5. Create a GitHub compare link between the two commits: https://github.com/dart-lang/pub/compare/<base>...<target>
6. For example, current stable to dev: dart-lang/pub@9f41ae1...0cbaf7a
7. Then I can browse the commits for anything relevant.

This works for most situations, but if not I just look at the history before the most recent commit found in DEPs.

Sidenote: For the pub.dev site, update/deploys are quite often and separate from the SDK release, so I just watch the repository and ignore any PRs which don't seem necessary to document.

[MaryaBelanger]

@parlough 😱 I'm speechless! I think you've mentioned this method to me before, but seeing how simple it is (and assuming it's applicable to all the development that goes into Dart), is really a game changer. We'll have to talk more about this offline!

[parlough]

There are a few situations where that won't always work, but we can talk more about those offline :)