This guide describes how we prioritize and triage bugs in the Comet project. The goal is to ensure that the most impactful bugs — especially correctness issues that produce wrong results — are identified and addressed before less critical issues.
Every new issue is auto-labeled with requires-triage, and this applies to all issues, not just bug reports. The first triage decision for any issue is therefore whether it is a bug or an enhancement.
| Label | Description |
|---|---|
bug | Something is broken: wrong results, crashes, panics, regressions, test/CI failures |
enhancement | A request for new functionality or improvement: new expression/operator support, a new config, performance optimization, refactoring, or documentation |
Apply exactly one of these to every triaged issue. An issue must never carry both bug and enhancement. Classify from the actual content of the issue, not from the title wording: an issue titled “bug: ...” may really be a feature request, and a genuine defect may not mention “bug” in its title at all.
Only bugs receive a priority label (see below). Enhancements are not assigned a priority label through this process. Both bugs and enhancements may receive area labels.
Every bug should have exactly one priority label. When filing or triaging a bug, apply the appropriate label from the table below.
| Label | Color | Description | Examples |
|---|---|---|---|
priority:critical | Red | Data corruption, silent wrong results, security vulnerabilities | Wrong aggregation results, FFI data corruption, incorrect cast output |
priority:high | Orange | Crashes, panics, segfaults, major functional breakage affecting production workloads | Native engine panic, JVM segfault, NPE on supported code path |
priority:medium | Yellow | Functional bugs, performance regressions, broken features that have workarounds | Missing expression support, writer feature gaps, excessive spilling |
priority:low | Green | Minor issues, test-only failures, tooling, CI flakes, cosmetic issues | Flaky CI test, build script edge case, documentation generator bug |
Use this decision tree:
priority:critical. These are the most dangerous bugs because users may not notice the incorrect output.priority:high. Crashes are disruptive but at least visible to the user.priority:medium. The user can work around it (e.g., falling back to Spark) but it impacts the value of Comet.priority:low. Test failures, CI issues, tooling, and cosmetic problems.A bug should be escalated to a higher priority if:
priority:high crash is discovered to also produce wrong results silently in some cases → escalate to priority:criticalpriority:medium bug is reported by multiple users or affects a common workload → consider escalating to priority:highpriority:low CI flake is blocking PR merges consistently → escalate to priority:mediumArea labels indicate which subsystem is affected. A bug may have multiple area labels. These help contributors find bugs in their area of expertise.
| Label | Description |
|---|---|
area:writer | Native writer (Parquet and other formats) |
area:shuffle | Shuffle (JVM and native) |
area:aggregation | Hash aggregates, aggregate expressions |
area:scan | Data source scan (Parquet, CSV, Iceberg) |
area:expressions | Expression evaluation |
area:ffi | Arrow FFI / JNI boundary |
area:ci | CI/CD, GitHub Actions, build tooling |
The following pre-existing labels also serve as area indicators: spark 4, spark sql tests.
Every new issue is automatically labeled with requires-triage when it is opened. This makes it easy to find issues that have not yet been triaged by filtering on that label. Once an issue has been triaged, remove the requires-triage label and apply the appropriate priority and area labels.
When a new issue is filed:
bug or enhancement based on the content of the issue. The remaining steps about priority apply only to bugs.good first issue if the fix is likely straightforward and well-scoped.requires-triage label to indicate triage is complete.Periodically review open bugs to ensure priorities are still accurate:
priority:medium bug been open for a long time with user reports? Consider escalating.priority:high bug been fixed by a related change? Close it.priority:critical)These are bugs where Comet produces different results than Spark without any error or warning. Examples include:
ignoreNulls)When fixing correctness bugs, always add a regression test that verifies the output matches Spark.
priority:high)These are bugs where the native engine panics, segfaults, or throws an unhandled exception. Common patterns include:
ConstantFolding is disabled)Several bugs relate to how Comet plans hash aggregates across stage boundaries. The key issue is that Spark's AQE may materialize a Comet partial aggregate but then run the final aggregate in Spark (or vice versa), and the intermediate formats may not be compatible. The closed EPIC #2892 collects the historical reports and is a good starting point when a new one comes in.
The native Parquet writer has a cluster of known test failures tracked as individual issues, from #3417 to #3430. These are lower priority since the native writer is still maturing, but they should be addressed before the writer is promoted to production-ready status.
Triage is a valuable contribution that doesn't require writing code. You can help by: