119 lines
5.8 KiB
Markdown
119 lines
5.8 KiB
Markdown
---
|
|
name: forge-issue-filing
|
|
description: How to file a well-formed forge issue through the hive-forge CLI - check for an existing duplicate first (title-only grepping misses it, use server-side --search), pick a title that states the problem not the symptom, write a body that's the *problem*, and put any proposed fix in a follow-up comment rather than the issue description. Use this whenever you're about to run `hive-forge issue-create`, whenever you hit a bug/gap/usability problem and are about to file it rather than silently work around it, or whenever asked to write up a finding as an issue.
|
|
---
|
|
|
|
# Forge Issue Filing
|
|
|
|
Filing an issue is cheap to do badly and expensive to do badly at scale - a
|
|
vague title makes it unsearchable later, a missing dedup check produces a
|
|
duplicate someone else has to notice and close, and a description that
|
|
mixes "what's wrong" with "here's my fix" forces every reader to
|
|
untangle the two. None of this needs much extra effort, just doing the
|
|
steps in the right order.
|
|
|
|
## 1. Check for a duplicate before filing
|
|
|
|
`hive-forge list` has a server-side full-text `--search` flag that covers
|
|
title *and* body - use it before writing anything:
|
|
|
|
```sh
|
|
hive-forge list --search "keyword or two" --state all
|
|
```
|
|
|
|
Grepping `list`'s plain output only ever sees titles, so an existing issue
|
|
whose title doesn't happen to share your wording is invisible to that
|
|
approach even though its body describes the same problem - which is the
|
|
common case, not the exception, since you and whoever filed it first
|
|
almost never land on the same phrasing independently. Try a couple of
|
|
different keyword combinations (the symptom, the affected
|
|
component/verb) before concluding nothing exists; one search with the
|
|
wrong words is not evidence of absence. If you land on a candidate,
|
|
skim its body and comments before deciding it's actually the same
|
|
problem - a superficially similar title can be a different issue.
|
|
|
|
If you're filing something adjacent to work already grouped into a
|
|
milestone, `--milestone <name>` composes with `--search` and narrows the
|
|
search to that scope.
|
|
|
|
## 2. Title: the problem, not the symptom-of-the-moment
|
|
|
|
A good title is something a future full-text search would actually match.
|
|
Prefer naming the broken behavior or missing capability over a specific
|
|
error string or one-off symptom - "hive-forge list has no way to filter by
|
|
milestone" beats "list command confusing" or "can't find issues for
|
|
milestone 11 easily". If you're not sure which framing is more durable,
|
|
lean toward whatever a colleague hitting the *same underlying gap* through
|
|
a *different* symptom would still recognize.
|
|
|
|
## 3. Body: what's wrong, not how to fix it
|
|
|
|
The issue description should state the problem clearly enough that
|
|
someone unfamiliar with it understands what's broken/missing and, ideally,
|
|
how to reproduce it or where it bites. It is **not** the place for your
|
|
proposed implementation - post that as a **follow-up comment**, not baked
|
|
into the description:
|
|
|
|
```sh
|
|
hive-forge issue-create --title "..." --body "..." --label ... --assignee ...
|
|
hive-forge comment <number> --body "proposed fix: ..."
|
|
```
|
|
|
|
Why the split matters: the description is what search and future readers
|
|
land on first, and it should stay stable - "what's the problem" doesn't
|
|
change as a design evolves. A proposal is a specific point-in-time idea
|
|
that gets discussed, revised, or replaced entirely; if it's baked into the
|
|
description, either the description goes stale the moment the proposal
|
|
changes, or someone has to edit it to keep it current and lose the
|
|
history of how the thinking evolved. A comment thread naturally
|
|
preserves that evolution - the description doesn't need to.
|
|
|
|
If you already know roughly what the fix should look like, it's fine (good,
|
|
even) to say so in a comment right after filing - just keep it visibly
|
|
separate from the problem statement.
|
|
|
|
## 4. Labels: check the taxonomy, don't guess
|
|
|
|
Label names are repo-specific and an unresolved name in `issue-create
|
|
--label` errors out before the issue is even created (better than the
|
|
alternative, but still wasted effort if you guess wrong). If you don't
|
|
already know the repo's label scopes, list them first:
|
|
|
|
```sh
|
|
hive-forge repo-labels
|
|
```
|
|
|
|
Attach whatever scope labels the repo actually uses (commonly a `type/*`
|
|
and an `area/*`, but check - taxonomies differ per repo) when you
|
|
already know them - it saves a round trip. But don't stress over an
|
|
unlabeled issue: labeling what's already filed is what triage coverage
|
|
(`hive-forge lint unlabeled --scope <scope>`, and whatever agent/process
|
|
this hive runs to sweep it) exists for. Guessing at a label you're not
|
|
sure of just to avoid leaving it blank can do more harm than leaving it
|
|
for triage to get right.
|
|
|
|
## 5. Assignee: leave it to triage unless you know who owns it
|
|
|
|
Don't self-assign by default just because you filed it - filing and owning
|
|
are different things, and an issue you noticed isn't necessarily yours to
|
|
fix. Set `--assignee` only when you already know who should pick it up
|
|
(yourself included, if you're about to start on it immediately) or when
|
|
the hive's own triage convention says otherwise. When in doubt, leave it
|
|
unassigned and let it surface through the normal triage sweep (see the
|
|
**`forge-triage`** skill).
|
|
|
|
## Putting it together
|
|
|
|
```sh
|
|
hive-forge list --search "thing you think is broken" --state all # 1: dedup
|
|
hive-forge repo-labels # 4: taxonomy
|
|
hive-forge issue-create \
|
|
--title "the problem, stated durably" \
|
|
--body "what's wrong, how to reproduce, where it bites" \
|
|
--label area/whatever --label type/bug
|
|
hive-forge comment <number> --body "proposed fix, if you have one" # 3: comment, not description
|
|
```
|
|
|
|
This is the filing mechanics only - the **`forge-workflow`** skill covers
|
|
the surrounding etiquette (never call the forge API directly, `@name`
|
|
subscribes, read before you comment) and applies just as much here.
|