GitHub Issue Labels

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-bulkio-backup-restore

  • A-bulkio-import

  • A-bulkio-schema-changes

  • A-core-kv

  • A-core-libroach

  • A-core-partitioning

  • A-cli

  • 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-tools-build

  • A-tools-roachprod

  • A-tools-workload

  • A-sql-json

  • A-sql-name-resolution

  • A-sql-optimizer

  • A-sql-parser

  • A-sql-execution

  • A-sql-type-system

  • A-web-ui

  • A-metrics

  • A-configuration (cluster settings, licensing, etc)

  • … more

• B-uild (if this is a build-specific issue, the build that the issue occurs for. Most issues won’t have a B- label.)

  • B-os-bsd

  • B-os-linux

  • B-os-macos

  • B-os-windows

  • B-arch-arm

  • B-unsupported-arch

• 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.)

  • backport-1.1.x

  • backport-2.0.x

• 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-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-investigation: it represents an investigation. Further steps may change/add C-label(s).

  • C-performance: performance of queries or internals. Solution not expected to change functional behavior, only performance.

  • 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-security-disclosure: this issue represents a security disclosure.

  • C-technical-advisory: this issue caused a technical advisory. Must be used with one or more branch-release-xx.x labels to indicate the affected major versions.

  • C-test-failure: this issue represents a test failure.

  • 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, or through a specific engineering process)

  • 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-roachtest: this issue was created as a result of a roachtest failure

  • O-sre: this issue was created by an SRE or is important to the SRE team

  • O-premortem: this issue is a premortem action item

  • O-postmortem: this is a postmortem action item

  • O-qa: this issue was discovered during manual QA of a feature

• P-riority (all C-test-failure, O-roachtest, O-support, O-premortem, O-postmortem, and O-qa issues must have priorities)

  • P-0: highest priority, equivalent to release-blocker, expected to be fixed within two weeks (14 days)

  • P-1: high priority, expected to be fixed within one milestone (30 days)

  • P-2: medium priority, expected to be fixed within three milestones (90 days)

  • P-3: low priority

• 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:

  • branch-release-20.1

  • branch-release-20.2

  • branch-release-21.1

  • … and so on for other releases

• 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.

    • Crash loops.

    • Leaked resources.

  • S-1-productivity: Severe issues that impede productivity of CockroachDB contributors.

    • Merge skews

    • 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 Cockroach Labs Engineering 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:

  • T-bulk-io

  • T-sql-observability

  • T-kv

• 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.