Skip to content

Commit e4166ec

Browse files
NodeJSmithCopilot
NodeJSmith
and
Copilot
authored
Release web ui improvements; clean up issue templates and add triage command (#248)
* clean up tmplates * clean up issues and add a command + update CLAUDE.md * update changelog and version * Update CLAUDE.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * add a documentation issue template * fix: address PR #248 review comments - Remove hardcoded @NodeJSmith from triage command doc, use "you" instead - Add acceptance criteria field to feature request issue template - Add changelog entries for template migration, triage command, and CLAUDE.md updates --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 37e8c2f commit e4166ec

File tree

13 files changed

+373
-109
lines changed

13 files changed

+373
-109
lines changed

‎.claude/commands/triage-issues.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
description: Audit and clean up GitHub issues — enforce labels, milestones, titles, and bodies per project conventions.
3+
---
4+
5+
# Triage Issues Command
6+
7+
Audit open GitHub issues **created by you** against the conventions in CLAUDE.md, fix anything that's off, and report what was changed.
8+
9+
## When to Use
10+
11+
Use `/triage-issues` when:
12+
- Issues have accumulated without proper labeling
13+
- You've batch-created issues and need to fill in details
14+
- Periodic hygiene check on the backlog (e.g., before a release or sprint)
15+
16+
## Arguments
17+
18+
$ARGUMENTS — parsed as:
19+
- `all` (default) — audit every open issue
20+
- `recent` — only issues created or updated in the last 14 days
21+
- `#123 #456` — audit specific issue numbers only
22+
23+
## How It Works
24+
25+
### Phase 1: Gather Current State
26+
27+
Run in parallel:
28+
```bash
29+
gh issue list --state open --author @me --json number,title,body,labels,milestone,createdAt,updatedAt --limit 200
30+
gh label list --json name,description,color --limit 100
31+
```
32+
33+
### Phase 2: Check Each Issue Against Conventions
34+
35+
Read the **GitHub Issues** section of `CLAUDE.md` for the current project conventions. For each open issue, check:
36+
37+
1. **Title** — must be a plain imperative description (no `[Bug]`, `[Feature]`, `Bug:`, `Feature -` prefixes). Type is conveyed by labels, not title.
38+
2. **Body** — must not be empty. At minimum needs a Description section and Acceptance Criteria (checklist).
39+
3. **Type label** — exactly one of: `bug`, `enhancement`, `documentation`, `CICD`, `tests`
40+
4. **Area label** — at least one `area:*` label unless the issue is cross-cutting (CI/CD, repo-wide docs, external integrations). Valid areas: `area:ui`, `area:websocket`, `area:scheduler`, `area:bus`, `area:api`, `area:config`, `area:apps`.
41+
5. **Size label** — one of `size:small` or `size:large`. Apply based on estimated scope.
42+
6. **Milestone** — must be assigned to one of the active milestones.
43+
7. **Priority label** — `priority:high` or `priority:low` only when clearly warranted (security issues, blockers = high; nice-to-haves = low). Most issues don't need a priority label.
44+
45+
### Phase 3: Fix Issues
46+
47+
For each issue that fails any check:
48+
49+
**Missing/bad title**: Use `gh issue edit <N> --title "<new title>"`
50+
**Empty/thin body**: Draft a body with these sections and apply with `gh issue edit <N> --body`:
51+
- `## Description` — what and why
52+
- `## Acceptance Criteria` — checklist of done conditions
53+
- (Optional) `## Proposed Solution` — if there's an obvious approach
54+
- Keep it concise. Don't pad with boilerplate.
55+
56+
**Missing labels**: Use `gh issue edit <N> --add-label "label1,label2"`
57+
**Wrong labels**: Use `gh issue edit <N> --remove-label "old" --add-label "new"`
58+
**Missing milestone**: Use `gh issue edit <N> --milestone "Name"`
59+
60+
### Phase 4: Report
61+
62+
After all fixes, output a summary table:
63+
64+
```
65+
## Triage Summary
66+
67+
| # | Title | Changes Made |
68+
|---|-------|-------------|
69+
| 42 | Fix flashing on UI | Added body, +area:ui, +size:small, milestone → HA Addon and UI |
70+
| 55 | Scheduler timeout | Title cleaned (removed [Feature] prefix), +area:scheduler |
71+
72+
### Stats
73+
- Issues audited: 27
74+
- Issues changed: 14
75+
- Issues already clean: 13
76+
```
77+
78+
### Phase 5: Flag Issues Needing Human Input
79+
80+
Some issues can't be fixed automatically:
81+
- **Stale issues** with no activity for 3+ months — flag for review, don't close
82+
- **Duplicate candidates** — flag pairs that look related, suggest merging
83+
- **Unclear scope** — issues where you can't write a meaningful body from the title alone
84+
85+
Present these in a separate section:
86+
87+
```
88+
## Needs Your Input
89+
90+
| # | Title | Question |
91+
|---|-------|----------|
92+
| 162 | Add guards against blocking I/O | Stale (4 months, no activity) — still relevant? |
93+
| 63/64 | Timeout for scheduler / Timeout for bus | Merge into single issue? |
94+
```
95+
96+
Use `AskUserQuestion` if fewer than 4 decisions are needed. Otherwise just list them for the user to address manually.
97+
98+
## Important Notes
99+
100+
- **Read CLAUDE.md first** every time — conventions may have changed since last run
101+
- **Never close issues** without explicit user approval
102+
- **Preserve existing body content** — when adding structure to an issue that has some text, wrap the existing text into the appropriate section rather than replacing it
103+
- **Batch gh calls** where possible to avoid rate limiting
104+
- Requires `gh` CLI installed and authenticated

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 0 additions & 39 deletions
This file was deleted.

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Bug Report
2+
description: Report a bug or unexpected behavior
3+
labels: ["bug"]
4+
body:
5+
- type: textarea
6+
id: description
7+
attributes:
8+
label: Bug Description
9+
description: What happened? Be specific.
10+
placeholder: "When I do X, Y happens instead of Z."
11+
validations:
12+
required: true
13+
14+
- type: textarea
15+
id: reproduce
16+
attributes:
17+
label: Steps to Reproduce
18+
description: Minimal steps to trigger the bug.
19+
placeholder: |
20+
1. Configure ...
21+
2. Start Hassette
22+
3. Observe ...
23+
validations:
24+
required: true
25+
26+
- type: textarea
27+
id: expected
28+
attributes:
29+
label: Expected Behavior
30+
description: What you expected to happen.
31+
validations:
32+
required: true
33+
34+
- type: textarea
35+
id: actual
36+
attributes:
37+
label: Actual Behavior
38+
description: What actually happened. Include error messages or log output if available.
39+
validations:
40+
required: true
41+
42+
- type: input
43+
id: hassette-version
44+
attributes:
45+
label: Hassette Version
46+
placeholder: "e.g., 0.5.0"
47+
validations:
48+
required: true
49+
50+
- type: input
51+
id: python-version
52+
attributes:
53+
label: Python Version
54+
placeholder: "e.g., 3.12.1"
55+
validations:
56+
required: true
57+
58+
- type: input
59+
id: ha-version
60+
attributes:
61+
label: Home Assistant Version
62+
placeholder: "e.g., 2025.12.0 (leave blank if N/A)"
63+
64+
- type: input
65+
id: os
66+
attributes:
67+
label: OS / Platform
68+
placeholder: "e.g., Ubuntu 24.04, Docker, macOS 15"
69+
70+
- type: textarea
71+
id: extra
72+
attributes:
73+
label: Additional Context
74+
description: Config snippets, logs, screenshots, or anything else that helps.

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Question or Discussion
4+
url: https://github.com/NodeJSmith/hassette/discussions
5+
about: Use Discussions for questions, ideas, or general conversation.

‎.github/ISSUE_TEMPLATE/documentation.md‎

Lines changed: 0 additions & 34 deletions
This file was deleted.

‎.github/ISSUE_TEMPLATE/documentation.yml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
name: Documentation
2+
description: Report missing, incorrect, or unclear documentation
3+
labels: ["documentation"]
4+
body:
5+
- type: textarea
6+
id: description
7+
attributes:
8+
label: Description
9+
description: What documentation is missing, incorrect, or unclear?
10+
validations:
11+
required: true
12+
13+
- type: dropdown
14+
id: type
15+
attributes:
16+
label: Type of Change
17+
options:
18+
- Missing documentation
19+
- Incorrect or outdated content
20+
- Unclear or confusing explanation
21+
- New example or tutorial needed
22+
validations:
23+
required: true
24+
25+
- type: textarea
26+
id: location
27+
attributes:
28+
label: Location
29+
description: Where does this documentation live (or where should it)?
30+
placeholder: "e.g., docs/guides/scheduling.md, README, API reference for Bus.on_state_change"
31+
32+
- type: textarea
33+
id: suggestion
34+
attributes:
35+
label: Suggested Improvement
36+
description: How should the documentation be changed or what should be added?
37+
38+
- type: dropdown
39+
id: contribute
40+
attributes:
41+
label: Would you be willing to contribute this change?
42+
options:
43+
- "Yes, I can write it"
44+
- "I can help review it"
45+
- "Just reporting"
46+
validations:
47+
required: true

‎.github/ISSUE_TEMPLATE/feature_request.md‎

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Feature Request
2+
description: Suggest a new feature or enhancement
3+
labels: ["enhancement"]
4+
body:
5+
- type: textarea
6+
id: description
7+
attributes:
8+
label: Feature Description
9+
description: What would you like to add?
10+
validations:
11+
required: true
12+
13+
- type: textarea
14+
id: motivation
15+
attributes:
16+
label: Problem / Motivation
17+
description: What problem does this solve? Why would it be useful?
18+
validations:
19+
required: true
20+
21+
- type: textarea
22+
id: solution
23+
attributes:
24+
label: Proposed Solution
25+
description: How should it work? Include code examples if helpful.
26+
render: python
27+
28+
- type: textarea
29+
id: alternatives
30+
attributes:
31+
label: Alternatives Considered
32+
description: Any other approaches you thought about?
33+
34+
- type: textarea
35+
id: acceptance
36+
attributes:
37+
label: Acceptance Criteria
38+
description: How do we know this feature is done?
39+
placeholder: |
40+
- [ ] Criterion 1
41+
- [ ] Criterion 2
42+
43+
- type: dropdown
44+
id: contribute
45+
attributes:
46+
label: Would you be willing to contribute this feature?
47+
options:
48+
- "Yes, I can implement it"
49+
- "I can help test it"
50+
- "Just suggesting"
51+
validations:
52+
required: true

0 commit comments

Comments
 (0)