You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@datafusion.apache.org by "andygrove (via GitHub)" <gi...@apache.org> on 2026/03/27 18:39:39 UTC
[PR] docs: add bug triage guide for prioritizing open issues [datafusion-comet]
andygrove opened a new pull request, #3812:
URL: https://github.com/apache/datafusion-comet/pull/3812
## Which issue does this PR close?
N/A - new documentation.
## Rationale for this change
We have 60+ open bugs with no systematic way to prioritize them. Critical correctness bugs (silent wrong results) were sitting alongside minor CI flakes with no differentiation. This makes it hard for contributors to know where to focus.
## What changes are included in this PR?
- New contributor guide page `docs/source/contributor-guide/bug_triage.md` documenting:
- Priority labels (`priority:critical`, `priority:high`, `priority:medium`, `priority:low`) with definitions and a decision tree
- Area labels (`area:writer`, `area:shuffle`, `area:aggregation`, `area:scan`, `area:expressions`, `area:ffi`, `area:ci`)
- Triage process for new and existing issues
- Prioritization principles (correctness over crashes, user-reported over test-only, core path over experimental)
- Common bug categories with examples
- Added the new page to the contributor guide table of contents
Note: The corresponding GitHub labels have already been created and applied to all 60 open bugs.
## How are these changes tested?
Documentation-only change. No code changes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: add bug triage guide for prioritizing open issues [datafusion-comet]
Posted by "andygrove (via GitHub)" <gi...@apache.org>.
andygrove commented on PR #3812:
URL: https://github.com/apache/datafusion-comet/pull/3812#issuecomment-4148375545
> Thanks @andygrove it is great, one thing to add is: I saw it on other large project, that by default the new issue could have a label `requires triage` so it would be clear the current state of the ticket
Great idea @comphead. I have added this.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: add bug triage guide for prioritizing open issues [datafusion-comet]
Posted by "andygrove (via GitHub)" <gi...@apache.org>.
andygrove merged PR #3812:
URL: https://github.com/apache/datafusion-comet/pull/3812
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org
Re: [PR] docs: add bug triage guide for prioritizing open issues [datafusion-comet]
Posted by "mbutrovich (via GitHub)" <gi...@apache.org>.
mbutrovich commented on code in PR #3812:
URL: https://github.com/apache/datafusion-comet/pull/3812#discussion_r3010654542
##########
docs/source/contributor-guide/bug_triage.md:
##########
@@ -0,0 +1,163 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Bug Triage Guide
+
+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.
+
+## Priority 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 |
+
+### How to Choose a Priority
+
+Use this decision tree:
+
+1. **Can this bug cause silent wrong results?** If yes → `priority:critical`. These are the most
+ dangerous bugs because users may not notice the incorrect output.
+2. **Does this bug crash the JVM or native engine?** If yes → `priority:high`. Crashes are
+ disruptive but at least visible to the user.
+3. **Does this bug break a feature or cause significant performance degradation?** If yes →
+ `priority:medium`. The user can work around it (e.g., falling back to Spark) but it impacts
+ the value of Comet.
+4. **Everything else** → `priority:low`. Test failures, CI issues, tooling, and cosmetic problems.
+
+### Escalation Triggers
+
+A bug should be escalated to a higher priority if:
+
+- A `priority:high` crash is discovered to also produce wrong results silently in some cases →
+ escalate to `priority:critical`
+- A `priority:medium` bug is reported by multiple users or affects a common workload → consider
+ escalating to `priority:high`
+- A `priority:low` CI flake is blocking PR merges consistently → escalate to `priority:medium`
+
+## Area Labels
+
+Area 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 Parquet writer |
Review Comment:
Does this include other data formats (that we might not support yet) like CSV and Iceberg?
##########
docs/source/contributor-guide/bug_triage.md:
##########
@@ -0,0 +1,163 @@
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Bug Triage Guide
+
+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.
+
+## Priority 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 |
+
+### How to Choose a Priority
+
+Use this decision tree:
+
+1. **Can this bug cause silent wrong results?** If yes → `priority:critical`. These are the most
+ dangerous bugs because users may not notice the incorrect output.
+2. **Does this bug crash the JVM or native engine?** If yes → `priority:high`. Crashes are
+ disruptive but at least visible to the user.
+3. **Does this bug break a feature or cause significant performance degradation?** If yes →
+ `priority:medium`. The user can work around it (e.g., falling back to Spark) but it impacts
+ the value of Comet.
+4. **Everything else** → `priority:low`. Test failures, CI issues, tooling, and cosmetic problems.
+
+### Escalation Triggers
+
+A bug should be escalated to a higher priority if:
+
+- A `priority:high` crash is discovered to also produce wrong results silently in some cases →
+ escalate to `priority:critical`
+- A `priority:medium` bug is reported by multiple users or affects a common workload → consider
+ escalating to `priority:high`
+- A `priority:low` CI flake is blocking PR merges consistently → escalate to `priority:medium`
+
+## Area Labels
+
+Area 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 Parquet writer |
+| `area:shuffle` | Shuffle (JVM and native) |
+| `area:aggregation` | Hash aggregates, aggregate expressions |
+| `area:scan` | Parquet scan / data reading |
Review Comment:
Similar question, since we already support CSV and Iceberg for scans.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: github-unsubscribe@datafusion.apache.org
For additional commands, e-mail: github-help@datafusion.apache.org