Labels, Milestones, Triaging ⚡

[jpmcb]

Labels, Milestones, Triaging ⚡

The following is a living issue, pinned to the top of cobra's GitHub issues for wide visibility, that represents the current labeling, triaging, milestone, and maintenance state of cobra. Maintainers, contributors, and users may refer to this in order to understand how bugs and features are being triaged and where their feature request may be in the maintenance cycle.

Inspired by projects like kubernetes-sigs/cluster-api and helm/helm

Labels 🏷️

kind/ - The type of issue

• kind/bug: A bug in cobra; unintended behavior
• kind/feature: A feature request for cobra; new or enhanced behavior
• kind/documentation: Documentation of cobra itself
• kind/testing: CI/CD, testing, etc. for cobra. Usually also gets the github label
• kind/rel-eng: Related to tagging and releasing cobra
• kind/upstream: Go modules cobra depends on
• kind/downstream: Related to projects/libraries that depend on cobra (like helm or kubernetes)
• kind/security: Related to security concerns in cobra itself. Refer to the security policy before opening any public issue.
• kind/cleanup: General cleanup of code, issues, etc.
• kind/deprecation: Related to a feature or part of code being deprecated
• kind/support: Questions, supporting users, etc.

area/ - The area of work that needs to be executed against

• area/cobra-command: Core cobra.Command implementations
• area/shell-completion: All shell completions
• area/docs-generation: Generation of docs
• area/flags-args: Changes to functionality around command line flags and args
• area/go: General Go, like go.mod or go.sum changes
• area/github: For changes to Github specific things not shipped in the library (like maintainers files, actions, etc)
• area/lib: Catch all for changes in the cobra library

triage/ - The state of an issue being triaged

• triage/needs-triage: Needs to be placed into a milestone, or be closed by maintainers. This label is removed once placed into a milestone.
• triage/blocked: Cannot move forward until some roadblock is lifted
• triage/needs-info: An issue that needs more investigation from maintainers or more info from the issue provider
• triage/duplicate: A duplicate issue. These issues are usually closed after receiving this label.

lifecycle/ - Where something is at in it's lifecycle

• lifecycle/needs-cla: The CLA still needs to be signed by the PR author. This label is blocking until the CLA is signed.
• lifecycle/active: Actively being worked on by a community member or maintainer. This label should also correspond with someone being assigned to the issue
• lifecycle/needs-proposal: For large features / bugs that need a proposal and community buy in
• lifecycle/approved: For large features / bugs that have a proposal and have gotten community buy in
• lifecycle/needs-pr: Ready for a PR from the community
• lifecycle/stale: Labeled by GitHub actions after 30 days of inactivity
• lifecycle/rotten: Labeled by GitHub actions after 30 days of having the lifecycle/stale label. Issues and PRs with this label will close after another 30 days of inactivity.
• lifecycle/frozen: Prevents GitHub actions from labeling Issues and PRs with lifecycle/stale or lifecycle/rotten
• lifecycle/wont-do: For issues and PRs the community has determined are not a priority and will not execute against

size/ - The size of the PR

Utilizes the pr-size-labeler to label PRs with a given size per number of lines changed

• size/XS: Denotes a PR that changes 0-9 lines
• size/S: Denotes a PR that changes 10-24 lines
• size/M: Denotes a PR that changes 24-99 lines
• size/L: Denotes a PR that changes 100-199 lines
• size/XL: Denotes a PR that changes 200 or more lines. Note: An XL pull request exceeds the recommended size of changes in a single PR. This is fine, but needs special attention from maintainers and may be rejected due to it's size. Make sure you are not addressing multiple issues in a single PR.

Nice to have, catch all maintenance labels:

• lgtm: Denotes "looks good to me" from maintainers and signals other collaborators that a PR is ready for additional review and merge
• good-first-issue: A good issue for a new collaborator to tackle
• help-wanted: An issue that the maintainers would like help on
• admin: For general admin tasks to be done usually by maintainers

Milestones 🪨

Milestones are used to categorize work and contributions into specific releases.

• The next milestone is used as a catch all for work that is being planned for some arbitrary upcoming release by the community
• The icebox milestone is used to track things that may need to be executed against eventually but are blocked, have the lifecycle/frozen label, etc.

Release cadence 🚂

cobra attempts to release quarterly.

This is a best effort.

Generally, a pinned release tracker issue is made that corresponds with the current release. On release, tags will be made on GitHub that than can be consumed by downstream Go modules.

Semver 🥇

Cobra follows Semantic Versioning. This generally means that:

• major bumps (i.e. v1.x.x to v2.x.x) have breaking changes (like deprecations, changing APIs, etc). Users of cobra will need to do some work to update their Go code to consume the latest major version
• minor bumps (i.e v1.1.x to 1.2.x) have no breaking changes, but include new features. Users of cobra will not need to do work to update their Go code to consume the latest minor version, but may choose to use the new features.
• patch bumps (i.e. v1.1.1 to v1.1.2) do not include new features or breaking changes but only backwards compatible bug fixes. Users of cobra will not need to do work to update their Go code to consume the latest patch version.

---

For more details, please refer to the Cobra User Contract

[jpmcb]

We'll let this sit for a bit and get community feedback. If all are good with this, I'll update the labels and projects to reflect this proposed state 👀

cc @marckhouzam @johnSchnake

[johnSchnake]

@jpmcb Great list!

One remark/question I had was regarding:

lifecycle/needs-proposal: For large features / bugs that need a proposal and community buy in

My initial reaction was that I'd like an additional lifecycle/needs-discussion for smaller PRs that just need some consensus but isn't a large feature with a formal doc. Upon thinking about it, that seems like it's probably overkill and that if an issue has lifecycle/active but not yet lifecycle/approved it is in the discussion phase. Is my understanding right?

[jpmcb]

Yeah, the lifecycle/ labels are where I struggled the most writing this.

I think your analysis is correct. But that also almost makes me think we don't need those proposal / approved labels. needs-pr might cover most of our cases where if that label isn't on an issue, it's still being discussed and gaining consensus from the community.

[marckhouzam]

This looks great @jpmcb, thanks for writing this up!
I will take a bit of getting used to 😄 but I think it will be worth it.

[ekamwctx]

Hello @jpmcb, superd documentation, such well organized labels will surely be of great help for everyone!

A question out of curiosity, what is the use case of the pr-size-labeler? Asking because I want to know if there is a good practice here that I can leverage with my team.

[jpmcb]

Hi @ekamwctx - the purpose of the size labelers is to give maintainers and collaborators an idea how how "big" a change might be. Quickly being able to evaluate that something is "extra small" with just 1 or 2 lines changes should indicate that it probably isn't a very big change. This happens automatically through this GitHub action. It's useful for us and helps to enable maintainers!

[yxxhero]

@jpmcb Hi. how often is the new patch version released?

[marckhouzam]

We don't usually do patch releases, unless there's a regression or a CVE.

[jpmcb]

I'm thinking it'll be beneficial to move this out to an actual document in the repo since issues aren't really the most portable thing. PR incoming!