diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..01d5d0ae --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,137 @@ +# Contributing guidelines + +## Principles and vision + +### [Roadmap to `v1.1.x`](./ROADMAP.md) + +### go version + +This repository supports _at least_ the 2 latest stable versions of the language. + +Example: when `go1.21` is out, we may require `go1.19` + +Any new language feature that is introduced should be guarded (and ideally, emulated for backward compatibility) +by go build flags, e.g. `go:build !go1.21`, `go:build go1.21`. + +We don't upgrade the required version of the compiler automatically: +changes to the go version requirement in `go.mod` will occur only if a new language feature is deemed really useful. + +Therefore, at any given time, older versions of the compiler might be supported. This not a promise, just a likely outcome. + +Example: if we introduce generics, `go1.18` would be a requirement. + +### The `pflag` compatibility promise + +**Programs using older versions of `pflag` should be able to compile in the future.** + +> In the spirit of the `go` language, we believe that the `golang` eco-system would benefit from a similar promise by this repository. + +The required version of the compiler may however evolve. + +We may use deprecation notices to advise users to move towards newer APIs. + +Older APIs will continue being honored, though. + +### The `pflag` promise of being a drop-in replacement of `flag` + +`pflag` is a drop-in replacement for `go`'s flag package, implementing +POSIX/GNU-style --flags. That's it. + +`pflag` will follow the evolution of the standard library `flag`, and continue to maintain the promise of being +a _drop-in replacement_ for `flag` (and then some of course, but at least that). + +### Versioning + +This package abides by `semver`. + +Hence: +* `v1.0.6` : patch +* `v1.1.0` : new feature + +As stated above, it is unlikely we ever issue a `v2.0.0` (breaking change). + +## Pull requests + +All contributions are much appreciated and welcome. There is no small contributions: additional documentation, examples, +tests, etc are all valuable additions, not just new features. + +### Linting + +This repository uses `github.com/golangci/golangci-lint/cmd/golangci-lint` as meta-linter, enforced by CI. +The set of rules may evolve over time. `revive` and `govet` are must-have. + +> TODO: agree on the initial .golangci.yml setup, with a no-nonsense approach to linting. Code quality without nitpicking... :) +> As a started, here is a sample configuration that I use on a daily basis for personal projects (no strong agenda on this): +> [golangci-lint.yml](https://github.com/fredbi/gflag/blob/master/.golangci.yml). + +### Testing + +Pull requests should include significant unit tests. + +This repository uses `github.com/stretchr/testify` framework for unit tests. + +> TODO: to be discussed, what we mean by "significant", e.g. >70% test coverage or so. + +### Documentation + +Keeping a compelling `godoc` documentation is part of the "drop-in replacement" promise. + +Any newly exposed API should come with a clear, readable description of what it does. + +Testable example are alway welcome (although not required). + +Conversely, internals only need comments if a particular caveat or expectation requires wording besides just code. + +### Dependencies + +So far, `pflag` has managed to build without _any_ external dependency. + +We may indulge into _a few_ dependencies, especially test dependencies, or things like `golang.org/x/...`. + +We should not need much more than that, unless we are talking about extensions (e.g. new flag types). See below. + +### Commit etiquette + +Please keep your commit title and description concise and to the point. + +Feel free to `git rebase -i`, `git commit --amend` etc, so this repository keeps a nice and readable git history, +without merge commits or fixup rescindments. + +### Contributor Licence Agreement + +Contributions are subject to a CLA DCO being signed off. + +> TODO: is this something that is still needed? Anyhow, check if the CLA terms are up to date. +> The Linux Foundation has introduced [EasyCLA](https://docs.linuxfoundation.org/lfx/easycla). +> I believe that `cla.assistant.io` is a bit old. + +### Signed commits + +Commits shall be [signed](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). + +> TODO: this requirement is debatable. +> On the one hand, it is certainly something many junior developers are perplex about. +> On the other hand, supporting so many major pieces of infrastructure is a big responsibility. + +### Linear history + +Please rebase your PRs to the current master before a merging can be done. All PR's will be squashed. + +## Contributed extensions + +New types, great features built on top of `pflag` etc are welcome. + +Considering adding those to the already rather rich collection of supported flag types is going always to be a long process. + +To address that, a new repository `spf13/pflag-contrib` may host such new ideas and (possibly breaking) innovations. + +That repository works under basically the same set of rules, but less stringent. + +* backward-compatibility for a contributed feature remains desirable, but not required +* contributors have a freer hand regarding dependencies +* documentation & testing are needed, possibly with a lighter touch +* introduction of new go features is possible - just guard your extension with `go: build gox.yz` + to avoid breaking other contributions + +> I am proposing a new git repo as I found rather impractical to maintain a nested `go.mod` in the main repo. +> Further, we most likely want to version contributed features independantly. diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 00000000..a2d08aa7 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,104 @@ +# `pflag` roadmap + +## Beef up the team of maintainers + +3 to 5 volunteers. No less, no more. + +Would be nice to open a slack or discord channel to make debate more lively. +Otherwise, we may use github discussions. + +## Agree on the [CONTRIBUTING guidelines](./CONTRIBUTING.md) + +There are quite a few debatable things there: let's find a minimal consensus +(possibly defer decisions about some details to a later stage). + +## Agree on a general direction + +Proposed principles: + +* promise of compatibility (i.e. no breaking `v2` ever) + +> Example: solving issue #384 by adding support for a default value would break compatibility. +> If we want to solve this issue, we need a new API. + +* prioritize use cases from `cobra` & `viper`, acknowledged as the main venues for importing `pflag` indirectly + +> Example: solving issue #250 typically comes from a `cobra` user. + +* prioritize code simplification & maintenance reduction over new features + +> Examples: PRs #235, #248, #332, #369, #378, #380 are representative of that effort + +* deflect stream of innovation, desire to share new ideas to some dedicated `contrib` repo + +> Examples: issue #246 is typically such a new flag type, requiring a specific import. + + +## Issue triage + +There are 88 outstanding issues. Let's triage them first. + +For every one of them: + * categorize: bug report, feature request/enhancement, code quality/testing, extensions ... (add new labels) + * post a comment/reply to the OP + +Proposed issue labels: +* bug +* duplicate +* invalid (not a bug) +* enhancement +* won't fix +* feature request +* extension +* code quality +* investigate/need repro + +Questions and the threads of answers may be used to populate a FAQ. + +## PR triage + +There are 70 outstanding PRs. Let's triage them first. + +Identify obsolete/won't do PRs, e.g. PR #206, probably #233 & #234 as well + +Prioritize merges as follows: + * bug fixes + * code quality/linting/fixups & minor refact proposals (add new labels) + * extra leeways/options (e.g. using the vararg `Option` pattern) + +Same labels as for issues may be used. + +At this point, isolate new features / enhancement proposals: they will be discussed later, once we get a clearer view. + +New PRs may come in with more refactoring and/or improvements to testing (e.g. use testify, add fuzz test...). + +## CI & tools + +* [ ] Re-enact CI (github actions), with (i) tests, (ii) - later - linting, (iii) govulneck +* [ ] Simplify (no real need for the tools in `verify`) +* [ ] Enforce linting + +## Repo climate + +* update & revamp repo badges (code coverage, CI passed, `pkg.go.dev` etc) +* shorter README, defer details to other docs (may be published as wiki or github pages) + +> I don't think we need to use github `Projects`: this is too small to justify this. +> Github `Discussions` could come in handy to collect thoughts from the community. + +## Setup a dedicated repo for extensions + +I suggest to create `github.com/spf13/pflag-contrib` to host such additions. + +> I don't have a knack for punch lines and catchy headlines. +> There is most likely a better name to be found. + +Identify PR candidates for extensions. We can manually clone or rewrite the most interesting ones. + +Popular non-breaking extensions might be refitted into the main repository at some point in the future. + +Examples: + +* PR #247 (new type) +* PR #374 (flag validation) +* PR #114 (localization)