Skip to content

Commit 0724338

Browse files
sjnimsclaude
sjnims
and
claude
committed
chore: improve label system and dependabot config
- Rewrite LABELS.md with tables, color swatches, and visual format - Add Label Application Guidelines and Label Combinations sections - Add Color Scheme Rationale documentation - Add 9 new labels: component:marketplace, component:mcp, scope:triggering, scope:validation, status:needs-design, status:analyzed, needs-analysis, triage, roadmap - Remove dependabot ignore rule for actions/checkout patches - Label count: 40 → 49 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 11895bf commit 0724338

3 files changed

Lines changed: 198 additions & 104 deletions

File tree

‎.github/LABELS.md‎

Lines changed: 160 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,168 @@
11
# Label Management
22

3-
This directory contains the canonical label configuration for the repository.
3+
This document describes the label system for plugin-dev.
44

55
## Files
66

77
- **labels.yml**: Source of truth for all repository labels
8+
- **LABELS.md**: This documentation file
89
- **workflows/sync-labels.yml**: Automated workflow that syncs label definitions on push to main
910
- **workflows/semantic-labeler.yml**: Claude-powered workflow that applies labels to issues and PRs
1011

1112
## Label Categories
1213

1314
### Type Labels
1415

15-
Default GitHub labels for issue/PR classification:
16+
Standard GitHub labels for issue/PR classification:
1617

17-
- `bug`, `documentation`, `duplicate`, `enhancement`, `invalid`, `question`, `refactor`, `chore`, `wontfix`
18+
| Label | Color | Description |
19+
| --------------- | -------------------------------------------------------- | -------------------------------------- |
20+
| `bug` | ![#d73a4a](https://placehold.co/15x15/d73a4a/d73a4a.png) | Something isn't working |
21+
| `documentation` | ![#0075ca](https://placehold.co/15x15/0075ca/0075ca.png) | Improvements or additions |
22+
| `duplicate` | ![#cfd3d7](https://placehold.co/15x15/cfd3d7/cfd3d7.png) | Already exists |
23+
| `enhancement` | ![#a2eeef](https://placehold.co/15x15/a2eeef/a2eeef.png) | New feature or request |
24+
| `invalid` | ![#e4e669](https://placehold.co/15x15/e4e669/e4e669.png) | Doesn't seem right |
25+
| `question` | ![#d876e3](https://placehold.co/15x15/d876e3/d876e3.png) | Further information requested |
26+
| `refactor` | ![#fef65b](https://placehold.co/15x15/fef65b/fef65b.png) | Code restructuring without behavior change |
27+
| `chore` | ![#c5def5](https://placehold.co/15x15/c5def5/c5def5.png) | Maintenance tasks |
28+
| `wontfix` | ![#ffffff](https://placehold.co/15x15/ffffff/ffffff.png) | Will not be worked on |
1829

1930
### Component Labels
2031

21-
Identify which part of the codebase:
32+
Identify which part of the codebase (cool blue/purple tones):
2233

23-
- `component:agent`, `component:command`, `component:docs`, `component:hook`, `component:skill`
34+
| Label | Color | Description |
35+
| ----------------------- | -------------------------------------------------------- | ------------------------ |
36+
| `component:agent` | ![#0052cc](https://placehold.co/15x15/0052cc/0052cc.png) | Agents layer |
37+
| `component:command` | ![#5319e7](https://placehold.co/15x15/5319e7/5319e7.png) | Commands layer |
38+
| `component:docs` | ![#d4c5f9](https://placehold.co/15x15/d4c5f9/d4c5f9.png) | Documentation files |
39+
| `component:hook` | ![#006b75](https://placehold.co/15x15/006b75/006b75.png) | Hooks layer |
40+
| `component:skill` | ![#1d76db](https://placehold.co/15x15/1d76db/1d76db.png) | Skills layer |
41+
| `component:marketplace` | ![#0366d6](https://placehold.co/15x15/0366d6/0366d6.png) | Marketplace manifest |
42+
| `component:mcp` | ![#032f62](https://placehold.co/15x15/032f62/032f62.png) | MCP integration |
43+
44+
### Scope Labels
45+
46+
Labels for plugin development concerns (warm coral/pink family):
47+
48+
| Label | Color | Description |
49+
| ------------------ | -------------------------------------------------------- | -------------------------------- |
50+
| `scope:triggering` | ![#e91e63](https://placehold.co/15x15/e91e63/e91e63.png) | Trigger phrase/description issues |
51+
| `scope:validation` | ![#f44336](https://placehold.co/15x15/f44336/f44336.png) | Plugin validation concerns |
2452

2553
### Priority Labels
2654

27-
Urgency classification:
55+
Urgency classification (heat map: hot → cool):
2856

29-
- `priority:critical`, `priority:high`, `priority:medium`, `priority:low`
57+
| Label | Color | Description |
58+
| ------------------- | -------------------------------------------------------- | ------------------------------- |
59+
| `priority:critical` | ![#b60205](https://placehold.co/15x15/b60205/b60205.png) | Blocking, security, or breaking |
60+
| `priority:high` | ![#d93f0b](https://placehold.co/15x15/d93f0b/d93f0b.png) | Important but not blocking |
61+
| `priority:medium` | ![#fbca04](https://placehold.co/15x15/fbca04/fbca04.png) | Should be addressed |
62+
| `priority:low` | ![#0e8a16](https://placehold.co/15x15/0e8a16/0e8a16.png) | Nice to have |
3063

3164
### Status Labels
3265

33-
Current state of work:
66+
Current work state:
3467

35-
- `status:blocked`, `status:in-progress`, `status:needs-repro`, `status:needs-review`
68+
| Label | Color | Description |
69+
| --------------------- | -------------------------------------------------------- | ------------------------ |
70+
| `status:blocked` | ![#e99695](https://placehold.co/15x15/e99695/e99695.png) | Blocked by dependencies |
71+
| `status:in-progress` | ![#90caf9](https://placehold.co/15x15/90caf9/90caf9.png) | Work in progress |
72+
| `status:needs-repro` | ![#f9c4f4](https://placehold.co/15x15/f9c4f4/f9c4f4.png) | Needs reproduction steps |
73+
| `status:needs-review` | ![#fff3b3](https://placehold.co/15x15/fff3b3/fff3b3.png) | Ready for review |
74+
| `status:needs-design` | ![#c5cae9](https://placehold.co/15x15/c5cae9/c5cae9.png) | Needs design decision |
75+
| `status:analyzed` | ![#a5d6a7](https://placehold.co/15x15/a5d6a7/a5d6a7.png) | Analyzed by Claude |
76+
| `needs-analysis` | ![#b39ddb](https://placehold.co/15x15/b39ddb/b39ddb.png) | Request Claude analysis |
3677

3778
### Effort Labels
3879

3980
Time estimates:
4081

41-
- `effort:small` (< 1 hour), `effort:medium` (1-4 hours), `effort:large` (> 4 hours)
82+
| Label | Color | Description |
83+
| --------------- | -------------------------------------------------------- | ----------- |
84+
| `effort:small` | ![#c2e0c6](https://placehold.co/15x15/c2e0c6/c2e0c6.png) | < 1 hour |
85+
| `effort:medium` | ![#bfdadc](https://placehold.co/15x15/bfdadc/bfdadc.png) | 1-4 hours |
86+
| `effort:large` | ![#f9d0c4](https://placehold.co/15x15/f9d0c4/f9d0c4.png) | > 4 hours |
87+
88+
### Community Labels
89+
90+
| Label | Color | Description |
91+
| ------------------ | -------------------------------------------------------- | -------------------- |
92+
| `good first issue` | ![#7057ff](https://placehold.co/15x15/7057ff/7057ff.png) | Good for newcomers |
93+
| `help wanted` | ![#008672](https://placehold.co/15x15/008672/008672.png) | Extra attention needed |
94+
| `idea` | ![#f9a825](https://placehold.co/15x15/f9a825/f9a825.png) | Feature idea or suggestion |
95+
| `showcase` | ![#6f42c1](https://placehold.co/15x15/6f42c1/6f42c1.png) | Community showcase |
96+
97+
### Dependency Labels
98+
99+
| Label | Color | Description |
100+
| ---------------- | -------------------------------------------------------- | ---------------------- |
101+
| `dependencies` | ![#0366d6](https://placehold.co/15x15/0366d6/0366d6.png) | Dependency updates |
102+
| `github-actions` | ![#000000](https://placehold.co/15x15/000000/000000.png) | GitHub Actions updates |
103+
104+
### Category Labels
105+
106+
Type of change:
42107

43-
### Community, Dependency, and Special Labels
108+
| Label | Color | Description |
109+
| -------------- | -------------------------------------------------------- | -------------------------------- |
110+
| `breaking` | ![#bd2130](https://placehold.co/15x15/bd2130/bd2130.png) | Breaking change (major version) |
111+
| `automation` | ![#28a745](https://placehold.co/15x15/28a745/28a745.png) | CI/CD and workflow improvements |
112+
| `optimization` | ![#2188ff](https://placehold.co/15x15/2188ff/2188ff.png) | Performance improvements |
44113

45-
**Community**:
114+
### Workflow Labels
46115

47-
- `good first issue` - Good for newcomers
48-
- `help wanted` - Extra attention needed
116+
| Label | Color | Description |
117+
| ---------- | -------------------------------------------------------- | ---------------------- |
118+
| `triage` | ![#ededed](https://placehold.co/15x15/ededed/ededed.png) | Needs initial review |
119+
| `stale` | ![#ededed](https://placehold.co/15x15/ededed/ededed.png) | No recent activity |
120+
| `pinned` | ![#fef2c0](https://placehold.co/15x15/fef2c0/fef2c0.png) | Never mark as stale |
121+
| `roadmap` | ![#0e8a16](https://placehold.co/15x15/0e8a16/0e8a16.png) | Long-term roadmap item |
49122

50-
**Dependency** (Dependabot):
123+
### Special Labels
51124

52-
- `dependencies` - Dependency file updates
53-
- `github-actions` - GitHub Actions updates
125+
| Label | Color | Description |
126+
| ------------ | -------------------------------------------------------- | --------------------------- |
127+
| `experiment` | ![#ff6ec7](https://placehold.co/15x15/ff6ec7/ff6ec7.png) | Experimental/testing |
128+
| `security` | ![#ee0701](https://placehold.co/15x15/ee0701/ee0701.png) | Security-related |
129+
| `reverted` | ![#666666](https://placehold.co/15x15/666666/666666.png) | Merged but later reverted |
54130

55-
**Special**:
131+
## Label Application Guidelines
56132

57-
- `experiment` - Testing/experimental changes
58-
- `pinned` - Never mark as stale
59-
- `reverted` - Merged but later reverted from codebase
60-
- `security` - Security-related issues
61-
- `stale` - No recent activity (auto-applied by stale workflow)
133+
### Required Labels
62134

63-
**Category** (type of change):
135+
Every issue and PR should have:
64136

65-
- `breaking` - Breaking change requiring major version bump
66-
- `automation` - CI/CD and workflow automation improvements
67-
- `optimization` - Performance and efficiency improvements
137+
1. **One type label**: bug, enhancement, documentation, refactor, chore, etc.
138+
2. **One priority label**: priority:critical, priority:high, priority:medium, priority:low
139+
3. **One effort label**: effort:small, effort:medium, effort:large
68140

69-
### Discussion Labels
141+
### Contextual Labels
70142

71-
Labels for GitHub Discussions categories:
143+
Apply when relevant:
72144

73-
- `idea` - Feature idea or suggestion
74-
- `showcase` - Community showcase
145+
- **Component labels**: When the change affects specific plugin components
146+
- **Scope labels**: When the change affects triggering or validation
147+
- **Status labels**: To track work progress
148+
- **Category labels**: For breaking changes, automation, or optimization work
149+
- **Community labels**: For contributor-friendly issues
150+
151+
### Label Combinations
152+
153+
Common label combinations for plugin-dev:
154+
155+
| Scenario | Labels |
156+
| --------------------------- | ----------------------------------------------------- |
157+
| Skill not triggering | `bug`, `component:skill`, `scope:triggering` |
158+
| New agent feature | `enhancement`, `component:agent`, `priority:*` |
159+
| Marketplace manifest issue | `bug`, `component:marketplace`, `priority:*` |
160+
| Validation script fix | `bug`, `component:docs`, `automation` |
161+
| MCP integration enhancement | `enhancement`, `component:mcp`, `effort:*` |
162+
| Hook development docs | `documentation`, `component:hook`, `effort:small` |
163+
| Command triggering bug | `bug`, `component:command`, `scope:triggering` |
164+
| Plugin architecture design | `enhancement`, `status:needs-design`, `roadmap` |
165+
| Dependabot PR | `chore`, `dependencies`, `effort:small` |
75166

76167
## Automatic Label Application
77168

@@ -87,25 +178,15 @@ The `semantic-labeler.yml` workflow:
87178

88179
### Labels Applied Automatically
89180

90-
| Category | Labels | Required |
91-
| --------- | ---------------------------------------------------------- | ------------- |
92-
| Type | bug, enhancement, documentation, question, refactor, chore | Yes (one) |
93-
| Component | component:\*, github-actions, dependencies | If applicable |
94-
| Priority | priority:critical/high/medium/low | Yes (one) |
95-
| Effort | effort:small/medium/large | Yes (one) |
96-
| Impact | breaking, security | If applicable |
97-
| Community | good first issue, help wanted | If applicable |
98-
99-
### Differences from Previous Labeler
100-
101-
The semantic labeler replaces the old `actions/labeler` which only applied labels based on file paths:
102-
103-
| Aspect | Old (path-based) | New (semantic) |
104-
| --------------------- | ---------------- | ----------------- |
105-
| Issues | Not supported | Full support |
106-
| Content understanding | File paths only | Semantic analysis |
107-
| Priority/effort | Manual only | Automatic |
108-
| Speed | ~5 seconds | ~30-60 seconds |
181+
| Category | Labels | Required |
182+
| --------- | ----------------------------------------------------------- | ------------- |
183+
| Type | bug, enhancement, documentation, question, refactor, chore | Yes (one) |
184+
| Component | component:\*, github-actions, dependencies | If applicable |
185+
| Scope | scope:triggering, scope:validation | If applicable |
186+
| Priority | priority:critical/high/medium/low | Yes (one) |
187+
| Effort | effort:small/medium/large | Yes (one) |
188+
| Impact | breaking, security | If applicable |
189+
| Community | good first issue, help wanted | If applicable |
109190

110191
### Skipped Cases
111192

@@ -127,74 +208,53 @@ The workflow skips:
127208
description: "Description here"
128209
```
129210
130-
2. **Create a PR** - the workflow runs in dry-run mode to preview the new label
211+
2. **Update LABELS.md** with the new label documentation
131212
132-
3. **Merge to main** - the label is created automatically
213+
3. **Create a PR** - the workflow runs in dry-run mode to preview
133214
134-
Or apply manually:
135-
136-
```bash
137-
gh label create "new-label" --color "ff6ec7" --description "Description here"
138-
```
215+
4. **Merge to main** - the label is created automatically
139216
140217
### Updating a Label
141218
142-
1. **Update labels.yml** (source of truth):
143-
144-
```yaml
145-
- name: "label-name"
146-
color: "new-color"
147-
description: "new description"
148-
```
149-
150-
2. **Create a PR** - the workflow runs in dry-run mode to preview changes
151-
152-
3. **Merge to main** - the label is updated automatically
153-
154-
Or apply manually:
155-
156-
```bash
157-
gh label edit "label-name" --color "new-color" --description "new description"
158-
```
219+
1. **Update labels.yml** with new color/description
220+
2. **Update LABELS.md** documentation
221+
3. **Create a PR** - preview changes in dry-run mode
222+
4. **Merge to main** - changes applied automatically
159223
160224
### Deleting a Label
161225
162226
Deleting labels requires manual action - the automated workflow only creates and updates labels (never deletes) for safety.
163227
164-
1. **Remove from labels.yml** (source of truth)
165-
166-
2. **Delete from GitHub manually**:
228+
1. **Remove from labels.yml**
229+
2. **Remove from LABELS.md**
230+
3. **Delete from GitHub manually**:
167231
168232
```bash
169233
gh label delete "label-name" --yes
170234
```
171235

172-
3. **Commit** labels.yml changes
173-
174-
### Syncing All Labels
236+
## Color Scheme Rationale
175237

176-
Labels are **automatically synced** when changes to `labels.yml` are pushed to main.
238+
| Category | Color Family | Rationale |
239+
| ---------- | ---------------------- | -------------------------------------------- |
240+
| Type | GitHub defaults | Familiar to all GitHub users |
241+
| Component | Cool blues/purples | Technical, structural feel |
242+
| Scope | Warm coral/pink | Distinct from components, user-facing issues |
243+
| Priority | Heat map (red → green) | Intuitive urgency indication |
244+
| Status | Soft pastels | Non-distracting state indicators |
245+
| Effort | Green → red gradient | Easy (green) to hard (red) |
246+
| Category | Semantic colors | Breaking=red, automation=green |
247+
| Workflow | Neutral greys | Background process labels |
177248

178-
- **PR preview**: When you open a PR that modifies `labels.yml`, the workflow runs in dry-run mode to show what changes would be applied.
179-
- **Automatic sync**: When the PR is merged to main, changes are applied automatically.
180-
- **Manual sync**: Use the GitHub CLI (see examples below) or trigger the workflow manually via GitHub Actions > Sync Labels > Run workflow.
249+
## Label Naming Conventions
181250

182-
## Label Naming Convention
183-
184-
- **Custom labels**: Use hyphens (`-`) not underscores (`_`) for multi-word labels
185-
- **Default GitHub labels**: Keep spaces as-is (`good first issue`, `help wanted`) for ecosystem compatibility
186-
- Use lowercase
187-
- Use colons (`:`) for category prefixes (`component:`, `priority:`, `status:`, `effort:`)
188-
- Keep names concise and descriptive
189-
190-
## Best Practices
191-
192-
1. **labels.yml is the source of truth** - always update it when changing labels
193-
2. **Use consistent colors** within categories (e.g., component labels use cool colors: blues, purples, and teals)
194-
3. **Keep descriptions clear** - they appear in the label picker
195-
4. **Don't create too many labels** - keep the set manageable (currently ~40)
196-
5. **Archive unused labels** rather than delete (consider dependencies)
251+
- **Prefixed labels**: Use colons for categories (`component:`, `scope:`, `priority:`, `status:`, `effort:`)
252+
- **Standard labels**: Keep GitHub defaults as-is (`bug`, `help wanted`, `good first issue`)
253+
- **Multi-word labels**: Use hyphens for custom labels, keep spaces for GitHub ecosystem compatibility
254+
- **Case**: All lowercase
197255

198256
## Label Count
199257

200-
The repository maintains a balanced set of labels - enough for good organization without overwhelming contributors. Check `labels.yml` for the current complete list.
258+
Current total: **~49 labels**
259+
260+
Balanced for good organization without overwhelming contributors. Check `labels.yml` for the complete list.

‎.github/dependabot.yml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
version: 2
22
updates:
3+
# GitHub Actions - Keep workflow action versions up to date
34
- package-ecosystem: "github-actions"
45
directory: "/"
56
schedule:
@@ -35,8 +36,4 @@ updates:
3536
update-types:
3637
- "minor"
3738
- "patch"
38-
# Ignore ultra-stable actions that rarely have meaningful patch changes
39-
ignore:
40-
- dependency-name: "actions/checkout"
41-
update-types: ["version-update:semver-patch"]
4239
open-pull-requests-limit: 5

0 commit comments

Comments
 (0)