| name | github-issue-template |
| description | Write well-formatted GitHub issues for the Altinity ClickHouse repository following team conventions. Covers bug reports for regressions, upstream bugs, and flaky test tracking. |
Skill: GitHub Issue Writing
Purpose
Write well-formatted GitHub issues for the Altinity ClickHouse repository following team conventions.
Covers bug reports for regressions, upstream bugs, and flaky test tracking.
Repository
- Altinity repo:
Altinity/ClickHouse — for Altinity-specific issues
- Upstream repo:
ClickHouse/ClickHouse — for upstream bugs (only if no existing issue found)
Issue Template: Bug Report
Use this template for all bug reports. Adapt sections as needed based on the bug type.
✅ *I checked [the Altinity Stable Builds lifecycle table](https://docs.altinity.com/altinitystablebuilds/#altinity-stable-builds-life-cycle-table), and the Altinity Stable Build version I'm using is still supported.*
## Type of problem
**Bug report** - something's broken
## Describe the situation
<1-3 paragraphs explaining:>
<- What the bug is>
<- When/how it was discovered (CI job, manual testing, customer report)>
<- Impact: crash, wrong results, error message, etc.>
This issue:
- <key fact 1, e.g., "Causes SIGABRT on debug/sanitizer builds">
- <key fact 2, e.g., "Returns error code 1001 on release builds">
- <key fact 3, e.g., "Is a pre-existing upstream bug dating back to July 2024">
---
## How to reproduce the behavior
### Environment
- **Version:** <exact version string>
- **Build type:** <release / debug / sanitizer>
### Steps
1. <step 1>
```sql
<SQL or commands for step 1>
- <step 2>
<SQL or commands for step 2>
- <step 3>
<SQL or commands for step 3>
Expected behavior
Actual behavior
On release builds
<exact error output>
On debug/sanitizer builds (if applicable)
<SIGABRT / crash details>
<stack trace, trimmed to relevant frames>
Root cause analysis
Additional context
CI failure
<Related PRs, upstream history, workarounds, etc.>
---
## Section Guidelines
### Describe the situation
- Lead with what's broken, not how you found it
- State the severity: crash vs error vs wrong results
- If it's an upstream bug, say so explicitly and mention since when
### How to reproduce
- Minimal steps — remove anything not needed to trigger the bug
- Include exact SQL queries and settings
- For fuzzer-found bugs: extract the crashing query from `fatal.log` and the required settings from the `Changed settings:` line
### Expected vs Actual behavior
- Be specific: "should return 3 rows" not "should work"
- For crashes: show both release behavior (error message) and debug behavior (SIGABRT + stack trace)
### Root cause analysis
- Optional but highly valued by the team
- Reference specific source files and functions if known
- If from stack trace analysis, include the key frames
### Additional context
- Always include CI links
- For upstream bugs: include the upstream CI history (query results from `play.clickhouse.com`)
- For regressions: reference the PR that introduced the change
- For flaky tests: include fail rate and time range
---
## Bug Type Variations
### Upstream Bug (not Altinity-specific)
Add to "Describe the situation":
```markdown
- Is a **pre-existing upstream bug** — present in the upstream ClickHouse CI since **<date>** with <N>+ occurrences
- Was detected in **Altinity Stable Build <version>** via the <job name> CI job
- No existing GitHub issue was found upstream tracking this failure
Add "Upstream CI history" subsection under Additional context:
### Upstream CI history
| Month | Upstream CI hits |
|-------|-----------------|
| <month> | <count> |
| ... | ... |
Regression from Specific PR
Add to Additional context:
### Related PR
- PR #<NUMBER>: <title> — introduced the change that caused this regression
Flaky Test
Add to Additional context:
### Flakiness data
- **Fail rate:** <X>% over the last 30 days
- **Affected build types:** <list>
- **First seen:** <date>
- **Pattern:** <consistent error vs varying>
Creating the Issue
gh issue create --repo Altinity/ClickHouse \
--title "<concise title>" \
--label "bug" \
--body "$(cat <<'EOF'
<issue body here>
EOF
)"
Common labels: bug, stable, antalya, antalya-25.8, 25.8, 25.8.16
Reference Issues
Good examples of well-formatted issues in the Altinity repo:
- #1412 — Regression with full reproduction, root cause, and workaround
- #1437 — Bug with suggested fix in the issue body
Related Skills
pr-ci-failure-triage — Identifies which failures need issues filedupstream-test-investigation — Gathers the data needed for the issue bodyupstream-ci-database-queries — Provides upstream CI history for cross-referencing
