CockroachDB's GitHub repo uses a system of GitHub labels to organize issues. The labels are organized into groups based on a capital letter prefix. The labels are grouped to enhance discoverability and help suggest a standard set of labels that issues should have.
All issues should have a C- label, at minimum.
The following is a complete list of the label groups. Each group itself might not be complete - for example, the code areas under the Area label category may change over time, and are not all represented in this proposal.
Each label group will have a unique prefix for all of the labels it contains, and a unique label color on GitHub. This helps organize issues: it makes it easy to see at a glance which label groups have been filled out for an issue, or if an issue has been tagged with two conflicting labels from the same group.
Labels that are otherwise hard to understand (like S-0, the label for the most severe bugs) will often be annotated with further details after a dash, to help remember what a label indicates. For example, instead of S-0, weâll be using S-0-corruption-or-data-loss. In addition, all labels should have a meaningful GitHub label description, unless itâs completely obvious from the name (A-rea labels, for instance, might not need one). This will help provide context to someone seeing the label for the first time.
A-rea (the code area and subsystem/feature that a bug belongs to). Due to the large number of subsystems in CockroachDB, the labels for subsystems should be further prefixed by the high-level area that they live in. Some areas may not have subsystems within - that should be up to the team that works on that code area. This proposal doesnât attempt to define what areas are valid - thatâs up to individuals, who should use their discretion for when to create area labels. During a project, it may be useful to have a label for that project, like A-sql-json. That label might not last past the completion of the project. Hereâs an incomplete list of examples:
A-pg-compat: postgres compatibility issue. Solution expected to adapt behavior to match pg's for equivalent input SQL. Some amount of backward compatibility might be broken in the process.
A-configuration (cluster settings, licensing, etc)
backport- (this indicates that an issue or PR should be backported to a prior release. This will supplant the 1.1.x and 2.0.x GitHub milestones.)
C-ategory (the high-level issue category. There should be only one category per issue):
C-bug: code not up to spec/doc, specs & docs are deemed correct. Solution expected to change code/behavior.
C-cleanup: technical debt, refactoring, loose ends to tie, etc. Solution not expected to change behavior.
C-investigation: it represents an investigation. Further steps may change/add C-label(s).
C-question: itâs a question rather than an issue like these other ones. Questions should probably be redirected to the forum or another means of communication, but they do come up in GitHub.
C-enhancement: new functionality. Solution expected to add code/behavior but preserve backward-compat with existing code (with exception of pg compatibility issues, where the enhancement may partially break backward compat with previous versions of CockroachDB in order to gain more compat with pg. See also A-pg-compat).
C-performance: performance of queries or internals. Solution not expected to change functional behavior, only performance.
C-security-disclosure: this issue represents a security disclosure.
C-wishlist: a wishlist feature item.
docs- status (labels that help the Docs team keep track of work - these may be added or removed over the lifecycle of an issue. Issues with PRs that have release notes donât need a docs- status.)
docs-known-limitation: this issue should be documented as a known limitation.
docs-todo: docs need to be updated based on info in this issue, not based on any code change.
E-xperience level: (call for participation: weâd appreciate or at least not mind if an external contributor tackled this issue. Most issues wonât have an E- label. Thereâs deliberately no E-difficult label. Note that this is similar to the GitHub-standard âgood first issueâ and âhelp wantedâ labels. Weâre choosing to use E- labels instead, as many other large projects have - including Rust and eslint. Weâll make sure to call this out prominently in CONTRIBUTING.md):
E-easy: this is an easy issue to tackle, requires little or no CockroachDB experience
E-intermediate: this is a less easy issue to tackle
O-rigin: (this issue originated from or was created on behalf of a non-employee)
O-community: this issue originated from the external community
O-support: this issue originated from or was create on behalf of a supported company
O-robot: this issue was created by a robot, like the nightly test runner
O-sre: this issue was created by an SRE or is important to the SRE team
P-latform (if this is an platform-specific issue, the platform that the issue occurs for. Most issues wonât have an P- label.)
release-blocker: designates that the issue is a release-blocker. A release should not be published until the issue has been fixed. This label should only be removed from an issue if the issue was incorrectly marked as a release-blocker. If a real release-blocker is fixed, the closed issue must retain the release-blocker label.Â This label is used with the following labels which indicate which release branch is affected by the blocker:
S-everity (to be used if an issue qualifies as a severe bug). Note that not every bug has to have a severity. A bug that isnât severe, like misaligned text in the UI or a typo in an error message, doesnât need a severity label.
S-0-corruption-or-data-loss: Unrecoverable corruption, data loss, or other catastrophic issues that canât be fixed by upgrading to a fixed version of the database. E.g.:
RocksDB corruption leaves the db in an invalid state. Nodes canât turn on as a result.
An acknowledged INSERT didnât in fact commit, or wrote something different from what was expected.
A transaction anomaly.
Incorrect SQL query responses. If you get bad data on a read, you may perform incorrect writes as a result.
Incorrect backups or dumps.
S-1-stability: Severe issues that can be fixed by upgrading CockroachDB to a version with a fix, but usually donât resolve by restarting the db.
Server panics due to internal assertions that occur unpredictably.
S-1-productivity: Severe issues that impede productivity of CockroachDB contributors.
Broken CI tests
Broken integration between tools (e.g. auto-creation of issues on test failures)
S-2-temporary-unavailability: temporary crashes or other availability problems. Can be worked around or resolved by restarting the db.
The server panics as a result of a particular kind of query.
A node is unresponsive.
S-3-ux-surprise: confusing or incorrect error message or behavior. Solution expected to combine doc changes with product UX changes.
T-eam: indicates the internal team that owns the issue. These labels are synced bidirectionally with the "Project" that the issue is contained in, which serves the same purpose. For example:
X: close reason.
X-duplicate: This is a duplicate of another issue.
X-invalid: Unable to reproduce, not actually an issue, etc.
X-wontfix: A legitimate issue, but weâre not going to fix it. Perhaps weâre deprecating the functionality the bug arises in, or itâs a feature request that isnât feasible.
There are some other, useful labels that weâll keep ungrouped, since they indicate special conditions that donât otherwise fall in a group:
meta-issue: this issue is an aggregation of many other issues.
do-not-merge: this PR label blocks bors from merging a PR
first-pr: applied to a contributorâs first PR to CRDB
fixitday: bugs fixed during a fixitday event
Finally, thereâs no category for the team that an issue relates to. Thatâs because GitHub projects are a useful way to organize issues by team, and having a label per-team seems like duplicate categorization and more overhead than necessary.