Allow non-functional package changes without bumping version number

[matthew-carroll]

Occasionally, I screw up package releases with typos or mis-linked images in informational files such as the README or LICENSE or CHANGELOG or other docs.

When I make those mistakes, I'd like to fix them without needing to bump my package version, and also delist the previous version.

I'd like for my package version to reflect the evolution of behaviors within that package, not the evolution of non-functional supplemental artifacts. In other words, I'd like to be able to change a README without changing my package version.

Similarly, there's a new feature on Pub that pulls some information from the pubspec. I'd like to be able to alter that information as well, without bumping the package version.

[jonasfj]

I have mixed feelings about this. Whenever I have to publish a new version to fixed a typo, I want to just edit it on pub.dev; but there are lots of reasons for not wanting to build this feature into pub.dev. Such as:

• Keeping packages self-contained: Today packages are self-contained, they often include README.md, LICENSE, test/, etc. this is nice because anyone who mirrors packages into their own custom package repository will get a self-contained package, which includes all relevant files.
• Encouraging a git workflow for packages: When working on a large team, it's nice that all changes go through code-review, it's nice that the entire github organization is configured to require branch protection, etc. While allowing modifications to README.md through the site doesn't preclude using a git workflow for all changes, it means that you suddenly need to enforce policies to prevent teammates from making modifications out-of-band, or pub.dev will need more advanced roles so that only so that we can prevent team members from using the feature. This is mostly relevant for large teams where you want all changes to pass through the same flow.
• Only offer one-way to do something: Basically avoid duplicating logic and keep things simple.
• Avoids inconsistencies: Allowing README.md to be edited on the site, could lead to inconsistencies where some changes makes into the current version on pub.dev, and don't make it into the README.md on github -- thus, the change will be lost / overwritten when next version is released.
• Avoid non-trivial technical overhead: If we allow editing of README.md after package publication we'll have to build UI for supporting this on pub.dev; setup testing, and we'll likely need to track change-history. Before long we've reinvented git -- all of this is non-trivial technical work that has to be maintained going forward. An argument could be made that we should prioritize other features.

---

Personally, I have sometimes abused the +<build-number> for fixing typos, example: https://pub.dev/packages/retry/versions/3.0.0+1/changelog

That's still publishing a new version. And it adds overhead to version-solving and everything. In an ideal world, maybe new build-number release should only be allowed to change metadata like README.md, CHANGELOG.md, dependency-constraints, etc, but forbid any actual changes to code. That might be a bit hard to enforce, and a very complicated features to build for very little gain. I don't know that it's feasible to enforce such kind of policy, or if we would even want to encourage it.

[matthew-carroll]

I want to be clear that this ticket does not imply "I want to just edit it on pub.dev". Such an approach might be one solution to the stated problem, but I'm not prescribing anything in particular. This ticket describes recurring frustrations with dealing with release overhead and messaging for changes that have no bearing on the technology that's shipped.

[isoos]

This ticket describes recurring frustrations with dealing with release overhead and messaging for changes that have no bearing on the technology that's shipped.

I'm curious: what is the release overhead that you are referring to? Also: do you have any specific suggestion in mind that you'd like to see changed here?

[matthew-carroll]

Overhead:

• Bumping the number (easy to forget to do when changing a README)
• Every new release creates another opportunity to accidentally screw something up, leading to yet more releases. I've had situations where I've ended up doing 2 or 3 immediate releases because I made dumb mistakes. But I don't remember what exactly those mistakes were.
• Shifting from the IDE over to Pub to delist any releases with mistakes
• Accumulating numerous public releases that obscure the releases that matter
• Messaging to users about how to interpret version numbers to work through the aforementioned noise

That's off the top of my head. There might be more. And others might contribute their own frustrations.

These might sound minor, but please keep in mind that these apply to situations where I simply want to fix a public facing typo, or add an image to a README. Those minor irritations outpace the size of the change I'm trying to make.

do you have any specific suggestion in mind that you'd like to see changed here?

Not really. I do my best not to be prescriptive when filing issues. I typically find that the developers who work on these issues like the freedom to explore multiple options. I also don't want to risk the ticket being closed because one specific solution wasn't deemed worthy.

If the Pub team finds a way to eliminate this irritation without adding another one, I'll do my best to be happy with whatever that solution may be.

[jonasfj]

I've had situations where I've ended up doing 2 or 3 immediate releases because I made dumb mistakes.

Yes, we've all done that :see_no_evil:

We have talked about two-stage publishing as a means to alleviate some of these concerns. Maybe, some day we'll find spare cycles to put some real effort into that -- it's not a perfect solution for this scenario, but would alleviate some of the cases where users have to republish.

[sigurdm]

and also delist the previous version.

FWIW we have "retraction" to support this part of the request.

I don't think we'll ever allow changing what is published with a given specific version number. The pubspec.lock tracks the hash of the package archive, and it would ring a bell if anything changed. I think retracting, and publishing a +1 package is the best option here.

@jonasfj @szakarias @isoos is there anything more we reasonably can do here? Or should we close the issue?

[isoos]

I don't think we'll ever allow changing what is published with a given specific version number.

That is correct, we don't allow updating the same version, or, if you retract or delete it (via a justified admin action) the version won't be reused again.

Agreed on the +1 versioning. Also, if the change is not substantial, maybe just delay it and bundle it with some minor bugfix down the line.