Shifting priorities across v1, v2, and v3

[meatballhat]

This discussion is primarily meant to make space for conversation about shifting development efforts to focus on v3. The details of what I have in mind would include:

• mark the v2 series as support mode only
  • push main branch as v2-maint branch, which is intended to be long-lived
  • v2.23.x ¹ will be the last minor release in the v2 series
  • the v2 series will only receive bug fixes and security fixes, meaning patch releases to v2.23.x only
• mark the v3 series as alpha
  • push v3-dev-main as main branch
  • push the first alpha tag in the v3 series so that projects may begin experimenting with features that are not available in v2
  • stop porting all changes from v2-maint to main
  • merge v3-dev-main to main and use the main branch for all v3 work
• mark the v1 series as unmaintained / unsupported
  • v1.22.10 will be the last release in the v1 series
  • delete the v1 branch (whoops! meant to do that a while ago!)
  • rename v1 branch v1-unsupported

Please contribute your thoughts in this discussion, especially if you see anything in these details that conflicts with your ability to keep using this library. Thank you! 💖

Footnotes

1. at the time of this writing, v2.23.0 was the current minor version, but more minor versions in the v2 series may arrive in the meantime, which I think is fine ↩

[dearchap]

v1. Yes freeze the release to v1.22.10 and say that no bug fixes, features will be supported. Delete the v1 branch altogether ? Not sure about that. Maybe give people 6 months advance warning before doing it ?

v2. Freeze features. Bug fixes only.

v3. I'm still not seeing a reason why someone would want to upgrade to v3. Right now it has no features that are not present in v2. There needs to able atleast one MAJOR feature in v3 which everyone is asking for prior to even releasing an alpha tag.

[meatballhat]

I guess I'm thinking about the v3 development line in terms of removing things from the API surface area and swapping out the use of stdlib "flag" to remove workarounds 🤔 So for me it's not really about attracting folks with new features as much as it's about cutting down on maintenance burden into the future.

[dearchap]

@meatballhat I'm thinking that for all practical purposes the stdlib flag along with our parse code satisfies almost all the use cases expect for

1. custom help flag without -h option
2. switch type flags

Instead of rewriting the entire parser we could copy the golang flag code and update it for the above 2 cases.

I've tried my hand at generics and I'm not really seeing a good value proposition yet compared to genflags.

[dearchap]

In terms of reducing the surface API what are your thoughts ?

[meatballhat]

Maybe reducing surface area isn't the right way to put it 🤔 There are a few design goals I'd like to be able to work toward that I think I've been assuming are in conflict with retaining the current API surface area and supporting work that's in flight that targets v2. I'm sure this isn't fully captured in #833 (I'll fill it in more!):

move most of the code into ./internal/...

• this Go capability wasn't available in the early days of this project
• it provides much clearer indication of what's intended to be the public API
• making such a change is fairly disruptive to open pull requests

ensure the primary way to use this library is via struct literals

• provides a clear distinction in API philosophy compared to (most?) other Go libraries in this space
• as part of this, ensure all public structs have usable pointer-to-zero values

support for wider range of arg types and type coercion helpers

• named positional arguments
  • prog <thing-1> <thing-2>
• more than a single expected value
  • --flag <val-1> <val-2> <val-3>
• one-or-more expected values
  • --flag <val> [val, val, ...]
• value "type annotations"
  • --flag @<val> or prog @<thing-1> <thing-2> where @ indicates path/url source of the arg value
  • --flag json:<val> where json: indicates the arg should be parsed as JSON
  • prog <thing-1> - <thing-3> where the literal - is interpreted as "stdin" with type information passed along
  • --flag @json:<val> or --flag @j:<val> where @json: or @j: indicates path/url of the arg value that should be parsed as JSON
  • prog <thing-1> @json:- where @json:- means "read the arg from stdin and parse it as JSON"

support for l10n and i18n

• internal support for help system templates in selected languages
• pluggable help system translation support (investigate library options?)

[meatballhat]

Ooh I remembered I also want to swap out the home-grown expect and refute testing functions with https://pkg.go.dev/github.com/stretchr/testify

[meatballhat]

• mark the v2 series as support mode only

  • push main branch as v2-maint branch, which is intended to be long-lived
  • v2.23.x will be the last minor release in the v2 series
  • the v2 series will only receive bug fixes and security fixes, meaning patch releases to v2.23.x only

⬆️ These are done ✅

• mark the v3 series as alpha

  • push v3-dev-main as main branch
  • push the first alpha tag in the v3 series so that projects may begin experimenting with features that are not available in v2
  • stop porting all changes from v2-maint to main
  • merge v3-dev-main to main and use the main branch for all v3 work

⬆️ These are done ✅

• mark the v1 series as unmaintained / unsupported

  • v1.22.10 will be the last release in the v1 series
  • delete the v1 branch (whoops! meant to do that a while ago!)
  • rename v1 branch v1-unsupported

⬆️ These are done ✅