torben
18ae28f918
Chemenu kompiliert Rohnotizen zu einem verlinkten, quellengebundenen Wiki: raw/ -> types/ + tools/ -> kb/ -> reports/. Was mechanisch ist, macht tools/wikitool; was Urteil braucht, macht ein Agent unter Contracts, deren Grenzen in Code durchgesetzt sind statt im Prompt. Dieser Commit ist der Startpunkt der oeffentlichen Historie. Die vorherige Entwicklung fand in einer privaten Instanz statt und ist nicht Teil dieses Repositorys; ihre Erzaehlung steht vollstaendig in CHANGES.md, das mit 44 Eintraegen von 0.1.0 bis 2.1.0 erhalten geblieben ist. Der mitgelieferte Korpus ist ein Testbett und eine Demo: 170 Seiten ueber den Stack selbst - Gates, Lint, Versionierung, Suche, das Wiki-Muster. Er dokumentiert das Werkzeug mit den eigenen Mitteln des Werkzeugs. Lizenz: AGPL-3.0 fuer den Stack (tools/, types/), CC-BY-4.0 fuer die Inhalte. Die Grenze zwischen beiden ist der Dateiplan, den dist export berechnet - siehe NOTICE.
83 lines
3.9 KiB
Markdown
83 lines
3.9 KiB
Markdown
---
|
|
type: types/instruction.md
|
|
name: issue-tracking
|
|
description: Where open work on this stack is tracked, and what the prio/ and size/ labels on a Gitea issue mean.
|
|
---
|
|
# Track open work as Gitea issues, not as prose in the repo
|
|
|
|
Open work on this stack lives at
|
|
<https://gitea.nehmer.net/torben/chemenu/issues>, one issue per work
|
|
package, and nowhere else. There is no `TODO.md`; there was, and every item in
|
|
it either became an issue or was already one, described twice.
|
|
|
|
That is the whole reason for this file: a second list is a second thing to
|
|
maintain, and the one that drifts is always the one nobody reads first. The
|
|
issue tracker wins that comparison outright - it has state, comments, labels,
|
|
and a link that survives the change it describes. A markdown file in the repo
|
|
has none of it, and it costs a publish to touch.
|
|
|
|
This instruction exists only in the dev repo. A distributed instance has no
|
|
issues at that URL, which is exactly why `dist export` excludes
|
|
`instructions/dev/` wholesale (see [tools/CONTRACT.md](../../tools/CONTRACT.md)).
|
|
|
|
## When to run
|
|
|
|
- Something is worth doing but not now. Open an issue; do not write it down in
|
|
the repo.
|
|
- A session's findings outgrow the change it was making - a gap in the tooling,
|
|
an assumption nobody has checked, a decision that needs the user.
|
|
- Prioritising: deciding what to pick up next, or re-labelling after the ground
|
|
moved.
|
|
|
|
## Steps
|
|
|
|
1. **Write the issue so it survives without you.** What is broken or missing,
|
|
why it matters, what "done" looks like as acceptance criteria, and the
|
|
specific files or commands involved. An issue that only makes sense to
|
|
whoever wrote it is a note, and notes were the problem.
|
|
|
|
2. **Give it exactly two labels: one `prio/`, one `size/`.** Both, always -
|
|
a priority without a cost is half a decision. Neither is a promise about
|
|
*when*; together they answer "what should I pick up in the time I have".
|
|
|
|
| Priority | Means |
|
|
|---|---|
|
|
| `prio/1` | Blocks or damages work in progress. Next. |
|
|
| `prio/2` | Accrues interest. Planned. |
|
|
| `prio/3` | Worth doing, waiting on a trigger. |
|
|
|
|
`prio/3` is not a graveyard. It means the issue's value is real but gated on
|
|
something outside it - a decision, another issue, a second instance
|
|
existing. Name that trigger in the issue, or the label is a polite no.
|
|
|
|
| Size | Means |
|
|
|---|---|
|
|
| `size/XS` | Minutes. Often just a decision or an observation to record. |
|
|
| `size/S` | One session, one publish, a clear cut. |
|
|
| `size/M` | Several files; a contract or instruction change; its own test effort. |
|
|
| `size/L` | Several sessions, or open design questions before the first commit. |
|
|
|
|
Size is effort, not importance. A `prio/1 size/XS` is the best thing on the
|
|
board; a `prio/3 size/L` is a thing to talk about before anyone starts.
|
|
|
|
3. **Re-label when the ground moves, and say why in a comment.** A trigger that
|
|
fired turns `prio/3` into `prio/2`. A design question that got answered can
|
|
drop a size. Silent re-labelling is how a board stops meaning anything.
|
|
|
|
4. **Close with what actually happened**, not with a commit hash alone: which
|
|
proposals were implemented, which were deliberately left out and why, and
|
|
what was verified. The issue is the only place that record survives - a
|
|
changelog entry says what changed, not what was decided against.
|
|
|
|
## Decision points
|
|
|
|
- **Issue or changelog?** An issue is work that is *not done*. `CHANGES.md` is
|
|
what shipped. A finished change needs both: the entry, and the issue closed
|
|
with the reasoning.
|
|
- **Issue or `kb/` page?** An issue is about *this stack* and is ephemeral - it
|
|
closes. A `kb/` page is compiled knowledge that stays true. Never put wiki
|
|
content findings in an issue, and never file a work item as a page.
|
|
- **Two labels feel too coarse?** They are meant to. A third axis - kind, area,
|
|
status - is the point at which a taxonomy starts needing maintenance of its
|
|
own, and this board has one maintainer.
|