Allow to notify the users about breaking changes and migrations via notice file

[orestesgaolin]

In the .NET world it is possible to include readme.txt file that gets open while installing new nuget package. It is used to notify about important breaking changes or migration strategy.

I suspect it would be awesome to have this kind of tool working somewhere between pub.dev, pub get and IDE extensions. I understand that this wouldn't be feature of the pub.dev per se, but I couldn't think of a better place to start a discussion about it.

How I imagine this could work

The library maintainer could include a new file (e.g. ./notice/notice-1.2.3.md) that would be opened whenever the package version changes from any lower to 1.2.3. The version change could be detected based on previous and current pubspec.lock entry. This file would either be printed in the console or opened in IDE.

If there are more files between previous and current version, then only open the most recent one.

[timsneath]

I like the notion: there are often times when package authors want to communicate with developers without them having to manually root through each individual CHANGELOG for interesting aspects. You could conceive that dart pub upgrade might be able to create a concatenated changelog for all packages that it upgraded.

One significant difference between these two package ecosystems, however, is that Dart has a much stricter adherence to semantic versioning. As you probably know, but others may not, NuGet predates the popularity of semver and uses version ranges. As I understand it, it's quite common to see dependencies that look like [2.0,) (meaning that the dependency is for any version >2.0.

As a result, it's less likely that a Dart package will have critical breaking changes that an app will unwittingly consume. That's not to say that there's no value of a feature like this, obviously, just that mirroring the NuGet model isn't necessary the right approach.

[sigurdm]

We have discussed aggregating CHANGELOG entries for all upgraded versions on pub upgrade before without doing much about it.

I think it would be a nice feature - there are some questions to discuss:

• how to best present this to the user (it might be very overwhelming to get this on stdout).
• Are the changelogs well-formatted enough that we can reasonably do this (pub.dev parses changelogs and extracts versions when it can: https://github.com/dart-lang/pub-dev/blob/master/app/lib/shared/markdown.dart#L349) we could probably get away with the same logic.

[orestesgaolin]

Taking into account that there's no common convention for CHANGELOG.md I'd suggest introducing a new file to store this kind of warnings/notifications. Let's say they could be limited in length, use fixed naming convention, and support only basic markdown e.g. for links.

[isoos]

there's no common convention for CHANGELOG.md

There are a few, e.g.

• The current format that pub.dev is parsing. I couldn't point to a clear specification of it, but we support a variety of differences that people are using on pub.dev. (if you package's Changelog tab has nice table formatting, then we were able to parse it correctly.
• There are elaborate changelog formats like this one: https://keepachangelog.com/en/1.0.0/

I'd rather add parsing support for these (including recognized patterns like **BREAKING CHANGES**), than introduce yet another file format with non-trivial discoverability.

[sigurdm]

We could add a validator on upload that the changelog is parsable, we have one that it contains the current version - that already saved me several times!

[jonasfj]

It seems like a possible feature could be aggregate changelog entries from all the upgraded packages and write them to a file like: .dart_tool/pub/changelog-entries.md or .dart_tool/pub/upgrade-log.md.

This has several advantages:

• We don't pollute stdout from dart pub get,
• It's easy for an IDE to open the file and render it as markdown,
• We can include additional information such as a table of package versions upgraded, newest version available, etc.
• We probably use features such as <details><summary> to collapse hide changelog entries for each package.
• We could conceivably create a new headline in markdown with Upgrade at <date-time>, such that we always append to .dart_tool/pub/upgrade-log.md never deleting old upgrade notices.

We would need to parse markdown in the dart pub client, as well as running the output through an HTML sanitizer (even if we don't render markdown to HTML, we need to strip any potentially malicious HTML tags).

Formalizing the changelog format seems very reasonable. We can still have the pub.dev parser accept more than what the dart pub publish validator will allow.

---

Another option is to have the dart pub compile a upgrade log on the basis of two pubspec.lock files, which could be fetched out of git log pubspec.lock or something like that. But this might be closer to an IDE integration feature, although implementing some of it in dart pub would certainly make it easier to support in multiple IDEs.

[sigurdm]

This is still relevant.

[Levi-Lesches]

@sigurdm Is there anything we could do to help move this along? It's an interesting feature, and I find myself usually doing:

• dart pub upgrade regularly, with no concern
• dart pub upgrade --major-versions sparingly, checking each package's changelog on Pub before testing

Usually, most packages don't break the specific APIs I'm using, so I'm being diligent even though I don't need to go through all that effort. Having a small list presented to me so I can quickly see if anything relevant changed would save me a lot of time and worry going forward.

[sigurdm]

Is there anything we could do to help move this along?

Not sure (of course upvote this issue to help us prioritize).

I think the pub team need to sit down and formalize the changelog format enough that we can somewhat reliably extract a series of versions from a changelog. This format needs to be validated by the package score on pub.dev, and then build this into the pub client.

Are you using dependabot for your projects? It already has this mechanism built in, and presents the changelogs entries (by some heuristic) in the PRs.

[Levi-Lesches]

Actually, some of my main projects are either not on GitHub or run entirely in offline environments. In the first case, Dependabot isn't set up of course, but in the second case, I want to update as rarely as possible, instead of staggering updates throughout the year.

[sigurdm]

Fair enough.

I cannot give you an ETA, but this is something we want to do eventually.