Skip to content

docs: add Issue Management guidelines to CONTRIBUTING.md #170

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
0xaskr merged 1 commit into from
Apr 7, 2026
Merged

docs: add Issue Management guidelines to CONTRIBUTING.md #170

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,64 @@ uv run pytest tests/ -v

Pre-commit hooks will run `ruff check --fix`, `ruff format`, `trailing-whitespace`, and `check-added-large-files` automatically on each commit.

## Issue Management

### Title Convention

All issue titles must start with a type prefix:

| Prefix | Usage | Label |
|--------|-------|-------|
| `[Bug]` | Bug report | `bug` |
| `[Feature]` | Feature request | `enhancement` |
| `[Epic]` | Large milestone or roadmap | `epic` |
| `[Perf]` | Performance issue or optimization | `performance` |
| `[Design]` | Kernel design proposal | `design-proposal` |
Comment on lines +108 to +114
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The 'Title Convention' table is missing prefixes for the documentation and question labels, which are listed as 'Type labels' in the Labels section (line 130). Since the guide states that all issue titles must start with a type prefix, these should be explicitly defined to ensure consistency and guide contributors correctly.

Suggested change
| Prefix | Usage | Label |
|--------|-------|-------|
| `[Bug]` | Bug report | `bug` |
| `[Feature]` | Feature request | `enhancement` |
| `[Epic]` | Large milestone or roadmap | `epic` |
| `[Perf]` | Performance issue or optimization | `performance` |
| `[Design]` | Kernel design proposal | `design-proposal` |
| Prefix | Usage | Label |
|--------|-------|-------|
| [Bug] | Bug report | bug |
| [Feature] | Feature request | enhancement |
| [Epic] | Large milestone or roadmap | epic |
| [Perf] | Performance issue or optimization | performance |
| [Design] | Kernel design proposal | design-proposal |
| [Docs] | Documentation improvement | documentation |
| [Question] | General question or clarification | question |


Issues without a prefix should have one added during triage.

### Priority

| Priority | Meaning | Response Time |
|----------|---------|---------------|
| `P0` | Blocking — affects core functionality or CI | Immediate |
| `P1` | Important — must complete in current iteration | Start within a week |
| `P2` | Improvement — can be scheduled for later | Planned |
Comment on lines +120 to +124
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist bot Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

In the Priority table, 'Planned' is listed as a 'Response Time' for P2 issues. This term describes a status rather than a temporal expectation. Consider using a more specific time-based description to align with the 'Immediate' and 'Start within a week' values used for P0 and P1.

Suggested change
| Priority | Meaning | Response Time |
|----------|---------|---------------|
| `P0` | Blocking — affects core functionality or CI | Immediate |
| `P1` | Important — must complete in current iteration | Start within a week |
| `P2` | Improvement — can be scheduled for later | Planned |
| Priority | Meaning | Response Time |
|----------|---------|---------------|
| P0 | Blocking — affects core functionality or CI | Immediate |
| P1 | Important — must complete in current iteration | Start within a week |
| P2 | Improvement — can be scheduled for later | Best effort / Next iteration |


All new issues must be tagged with a priority label. Untagged issues default to `P2`.

### Labels

**Type labels:** `bug`, `enhancement`, `documentation`, `question`
**Priority labels:** `P0`, `P1`, `P2`
**Special types:** `epic`, `performance`, `design-proposal`, `cpu-ref`
**Community labels:** `good first issue`, `help wanted`

The `cpu-ref` label must be added to any issue or PR that modifies code under `tops/cpu/`.

### Issue Lifecycle

```
Created → [Optional] Triage/Assign → In Development → PR linked (Closes #N) → Auto-closed on merge
```

- Use the appropriate [issue template](.github/ISSUE_TEMPLATE/) when creating an issue.
- Include the title prefix and a priority label.
- Assignees default to unset; assigned later by a maintainer or automation.
- PRs should use `Closes #N` to link the related issue; the issue is auto-closed on merge.

### Epic & Sub-issues

- Epic issues use the `[Epic]` prefix and `epic` label.
- Parent-child relationships are established via the GitHub Sub-issues API.
- The Epic body should include a `- [ ] #N` checklist for progress tracking.
- Each sub-issue should be independently completable with a single PR.
- Epic issues are manually closed after all sub-issues are resolved.

### Issue Types (Supplementary)

The organization has configured GitHub Issue Types (Bug / Feature / Goal / Task / SubTask). Setting the appropriate type when creating an issue is optional. **Title prefixes and labels are mandatory** — Issue Types do not replace them.

## Code Review Process

### General Changes
Expand Down
Loading