Tag 1.0.8 does not follow semver best practices

[tendervittles]

https://peerdh.com/blogs/programming-insights/semantic-versioning-best-practices-in-go

Release 1.0.8 alters the name of an exported variable. This is a breaking, incompatible, change.

It triggers compile failures in code relying on the old name.

This is avoided in go modules bumping the major, not the patch, of the release.

[nlnw]

They also broke users of cobra since usage of that var hasn't been updated in cobra.

[nadeemc]

Can use replace in go.mod to workaround this until the fix is merged: spf13/cobra#2303 (comment)

[tomasaschan]

O@tendervittles I'm aware, but realized this first after 1.0.8 was released. While not optimal, I feel there are two things that make this "okay-ish" despite being technically against the semver promise:

1. There is no way this is breaks silently - if you use the affected bits, you'll get a compile error. If you don't get a compile error, it can't affect your code.

2. The fix is extremely easy to execute in your own code, and due to the global nature of the renamed fields and typical use patterns of flag parsing (once at the application entry point), it likely requires changing code in only one or two places across a code base.

I've updated the release notes to make note of this, and filed a PR to Cobra (which has since been merged and released) to handle the breaking change. I have not seen notifications about anything else breaking that wasn't breaking because Cobra wasn't compatible, which should no longer be an issue (go mod tidy should fix that). If I see signs of those breaking because of direct usage of pflag in the other places, I'll try to file PRs to help out there too.

Edit: I just realized that Cobra didn't actually publish a release yet, so things like go get -u ./... still break builds that depend on Cobra but not directly on pflag. I'll tag a 1.0.9 shortly (once my 1yo allows me to sit at my computer for ten minutes...) to rectify.

I apologize for the inconvenience this caused.

[alexpts]

Why not release v2? The current version breaks code in many projects and is a problem now.

[nadeemc]

I tend to agree with @tomasaschan on this.

The issue wasn't that pflag didn't bump to v2, it's that the cobra release wasn't coordinated for the same time as pflag--that can be improved on in the future, but it's relatively easy to work around this / revert a version upgrade in your project, until cobra is synced up. Not ideal, but breaks happen.

I'd argue going the v2 route is the bigger pain for such a small change, albeit breaking, because it wouldn't automatically get picked up by "go get" until your import path in the projects changed.

Anyway, hopefully cobra has a release bump shortly and we can all be good to go.

[Airblader]

The issue [was] that the cobra release wasn't coordinated for the same time as pflag--that can be improved on in the future

These are fundamentally two separate projects, there should be no need to coordinate releases. Moreover, it is possible that you cannot update one of the two for some reason, so you'd still run into this issue.

I'd argue going the v2 route is the bigger pain for such a small change

Semantic versioning explicitly describes that this scenario should be dealt with by publishing 1.0.9 reverting the offending change, which would be a low-pain effort. In fact you could simply introduce an alias to remain compatible with both 1.0.8 and <1.0.8.

[tomasaschan]

v1.0.9 has been tagged and should show up in package indexes and caches shortly. The old names have been re-introduced with deprecation warnings in docstrings (I don't know of a better way to signal deprecation in Go code; if you do, please let me know!)

I'm likely to remove these in a future release before 2.0 due to how cumbersome it is to bump major releases of Go libraries, and how easy it is to adjust to this fix, but v1.0.9 should at least ensure that users of Cobra are not affected by this until Cobra itself has had a release tagged that includes spf13/cobra#2303.

[philoserf]

Hey, this package is super popular, so I’m surprised this kind of slip-up happened. I’m really hoping there’s a review coming out soon to explain how the decision was made. From what I can tell, the main issue was changing the name of a public API. It wasn’t just deprecated; it was removed. Honestly, the real head-scratcher was the decision-making process.

[tomasaschan]

@philoserf This is a pretty good summary of the current state.

[thaJeztah]

I'm likely to remove these in a future release before 2.0 due to how cumbersome it is to bump major releases of Go libraries, and how easy it is to adjust to this fix

I would recommend keeping the deprecated bits. While it's trivial to correct in your own project, it's often not possible to do so if the use of the deprecated fields is in other dependencies, or indirect dependencies.

When using go modules, SemVer is unfortunately a strict requirement, so exported functions and types cannot be removed or have their signature changed without a major version update (which allows for multiple versions to be used in the dependency tree)