A Path to v2.0#482
Open
tomasaschan wants to merge 7 commits into
Open
Conversation
Run Go's own flag package test suite against pflag v2 (dot-imported as "flag") to keep the drop-in-replacement promise honest. The suite is the spec for v2: as the package is currently empty, every failure is an implementation gap to close (see v2/conformance/README.md for the gap list / TODO). The suite is build-tagged "conformance" so it does not affect the normal `go test ./...` run, and is Go-version aware: a separate copy of upstream flag_test.go is vendored per minor version, each pinned with a build constraint (e.g. go1.26 && !go1.27), so the CI matrix tests each supported Go release against that release's own flag tests and upstream changes surface as diffs. hack/sync.sh regenerates the copies (also wired to `go generate ./conformance/...`); a guard test fails loudly if the running toolchain has no vendored copy. Adds a non-blocking conformance-v2 CI job (continue-on-error until v2 is complete). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the second conformance promise (POSIX/GNU argument syntax) alongside the vendored stdlib flag suite, plus the machinery to reconcile the two when they conflict. - gnuposix_test.go: hand-written suite keyed to the POSIX Utility Syntax Guidelines (1-14) and the GNU long-option extensions. No reusable Go-native POSIX corpus exists to vendor, so each case cites the rule it checks. - divergences.json: single source of truth cataloguing the intentional differences between pflag and the stdlib flag package. POSIX wins, so the listed stdlib tests are *expected* to fail; each entry names them and the rule that overrides them. Categories: posix-overrides-stdlib, pflag-design-differs, pflag-omits-gnu-feature, not-implemented-yet. - hack/oracle: reads `go test -json` and gates CI on the catalogue rather than raw pass/fail: green iff failures match the documented set exactly (catches regressions and silently-resolved divergences). The top-level "status" field tolerates a build failure while "bootstrapping" so CI is green during v2 build-out; "not-implemented-yet" entries are lenient (tolerated when failing, retirable when they start passing). - internal/divergence: catalogue types + parsing, shared by the manifest test and the oracle (no build tag, no v2 dependency). CI conformance-v2 job now pipes the suite through the oracle and drops continue-on-error; it is green now (bootstrapping) and tightens to enforcing once v2 compiles. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
There are a lot of things in this library that I'd love to fix - but most of the fixes become a lot more complicated to execute on, because we also need to maintain backwards compatibility. (The response to release v1.0.8 shows that this is clearly important to at least some, loud, part of the community.)
I no longer want to keep adding
//nolintcomments to allow for keeping code compatible with Go 1.12, released in 2019 with the last minor release published in 2020. I no longer want to fight to keep APIs and behavior consistent across umpteen almost but not quite identical implementations of parsing flag values to slices of various primitive types. I no longer want to keep names likeBlacklistin the public API.I'm opening this PR in very early draft to start carving a path to a new major version of this library, that allows us to fix all of the above without breaking semver promises. Before this is actually released, it is likely also a good idea to move it to an import path that is not tied to a single Github user's account - but we have to start somewhere. As a first step, I just want to have CI in place to start iterating.