docs(issues): describe resolution and linked issue history

commit: 35cc498aac2e9df93f1589b150003723b53e9e21
author: brice · 18h ago · 2026-10-22 18:14 UTC
committer: brice · 3h ago · 2026-10-23 09:28 UTC
parent: e95ffd9
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

2 files · +22 -7

M docs/issues.md +17 -6

@@ -1,13 +1,14 @@
1	1		# Issues
2	2
3		-	An issue records a task, a bug or a question about a repository: a title, a body, comments, and an open or closed state. Issues share the numbering of merge requests: after merge request 1, the next issue is number 2.
	3	+	An issue records a task, a bug or a question about a repository: a title, a body, comments, and an open, closed or resolved state. Issues share the numbering of merge requests: after merge request 1, the next issue is number 2.
4	4
5	5		```sh
6	6		ermite repo edit myrepo --issues owner
7	7		ermite issue create myrepo --title "Crash on start" --body "It crashes."
8		-	ermite issue list myrepo [--state open\|closed\|all]
	8	+	ermite issue list myrepo [--state open\|closed\|resolved\|all]
9	9		ermite issue show myrepo 2
10	10		ermite issue comment myrepo 2 -m "Reproduced."
	11	+	ermite issue resolve myrepo 2
11	12		ermite issue close myrepo 2
12	13		ermite issue reopen myrepo 2
13	14		```

@@ -17,6 +18,16 @@ ermite issue reopen myrepo 2
17	18
18	19		All commands take `--json`. `--body -` and `--body-file -` read standard input. A server needs the `issues` feature (`ermite version`); without it the commands, `repo edit --issues` and `token create --scope issue:write` are refused.
19	20
	21	+	## States and history
	22	+
	23	+	- Open: work remains.
	24	+	- Closed: closed without being resolved.
	25	+	- Resolved: fixed, either with `ermite issue resolve <repo> <n>` or by merging a closing reference.
	26	+
	27	+	The web list has Open, Closed and Resolved tabs. The web offers Close for open issues and Reopen for closed or resolved issues; manual resolution is CLI-only. Reopening clears the resolving merge request. A merge does not resolve an already closed issue. Existing issues closed by a merge are migrated to resolved without adding historical events.
	28	+
	29	+	The issue conversation interleaves comments and timestamped system rows for references, closure, reopening and resolution, with actor and merge request links. History is append-only: removing a current reference does not remove its history. At most 500 events are retained per issue; later events are omitted without preventing state changes or merges.
	30	+
20	31		## The `issues` setting
21	32
22	33		`ermite repo edit <repo> --issues off\|owner\|public`, shown by `repo show` (JSON field `issues`):

@@ -41,13 +52,13 @@ Merge requests and issues of a repository draw `#n` from one sequence, so a numb
41	52
42	53		A merge request and the issues of its repository are linked by `#N` in its text:
43	54
44		-	- Closing keywords close the issue when the merge request is merged, and only then: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved` (any case), then `#N`, with an optional `:` after the keyword. A list works: `fixes #3, #4 and #5`. They count in the title, the description and the commit messages, not in notes. Closing the merge request without merging closes nothing.
45		-	- Any `#N` in the title, description, notes or commit messages shows the merge request on the issue (`ermite issue show`, the API `references`), with its state and whether it closes the issue.
46		-	- A closed issue records the merge request that closed it ("closed by !N"). Reopening or closing by hand clears it.
	55	+	- Closing keywords resolve an open issue when the merge request is merged, and only then: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved` (any case), then `#N`, with an optional `:` after the keyword. A list works: `fixes #3, #4 and #5`. They count in the title, the description and the commit messages, not in notes. Closing the merge request without merging resolves nothing.
	56	+	- Any `#N` in the title, description, notes or commit messages shows the merge request on the issue (`ermite issue show`, the API `references`), with its state and whether it resolves the issue on merge.
	57	+	- A merge-resolved issue records the merge request that resolved it ("resolved by !N"). Reopening clears it.
47	58		- The links are recomputed whenever the merge request changes (a note added, edited or deleted, a push to its branch, a merge), so removing a mention removes the link.
48	59		- Words glued to the number (`abc#3`), `'` and `##3` are not references. Code spans are not skipped.
49	60
50		-	Limits: the 100 most recent commits of the merge request, 16 KiB of each text, 100 merge requests listed per issue. Only numbers of existing issues are linked: a mention of a number that does not exist yet is not filled in later. With issues `off`, nothing is closed.
	61	+	Limits: the 100 most recent commits of the merge request, 16 KiB of each text, 100 merge requests listed per issue. Only numbers of existing issues are linked: a mention of a number that does not exist yet is not filled in later. With issues `off`, nothing is resolved.
51	62
52	63		## Inbox
53	64

 # Issues
-An issue records a task, a bug or a question about a repository: a title, a body, comments, and an open or closed state. Issues share the numbering of merge requests: after merge request 1, the next issue is number 2.
+An issue records a task, a bug or a question about a repository: a title, a body, comments, and an open, closed or resolved state. Issues share the numbering of merge requests: after merge request 1, the next issue is number 2.
 ```sh
 ermite repo edit myrepo --issues owner
 ermite issue create myrepo --title "Crash on start" --body "It crashes."
-ermite issue list myrepo [--state open|closed|all]
+ermite issue list myrepo [--state open|closed|resolved|all]
 ermite issue show myrepo 2
 ermite issue comment myrepo 2 -m "Reproduced."
+ermite issue resolve myrepo 2
 ermite issue close myrepo 2
 ermite issue reopen myrepo 2
 ```
 All commands take `--json`. `--body -` and `--body-file -` read standard input. A server needs the `issues` feature (`ermite version`); without it the commands, `repo edit --issues` and `token create --scope issue:write` are refused.
+## States and history
+- **Open**: work remains.
+- **Closed**: closed without being resolved.
+- **Resolved**: fixed, either with `ermite issue resolve <repo> <n>` or by merging a closing reference.
+The web list has Open, Closed and Resolved tabs. The web offers Close for open issues and Reopen for closed or resolved issues; manual resolution is CLI-only. Reopening clears the resolving merge request. A merge does not resolve an already closed issue. Existing issues closed by a merge are migrated to resolved without adding historical events.
+The issue conversation interleaves comments and timestamped system rows for references, closure, reopening and resolution, with actor and merge request links. History is append-only: removing a current reference does not remove its history. At most 500 events are retained per issue; later events are omitted without preventing state changes or merges.
 ## The `issues` setting
 `ermite repo edit <repo> --issues off|owner|public`, shown by `repo show` (JSON field `issues`):
 A merge request and the issues of its repository are linked by `#N` in its text:
-- **Closing keywords** close the issue when the merge request is **merged**, and only then: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved` (any case), then `#N`, with an optional `:` after the keyword. A list works: `fixes #3, #4 and #5`. They count in the title, the description and the commit messages, not in notes. Closing the merge request without merging closes nothing.
+- **Closing keywords** resolve an open issue when the merge request is **merged**, and only then: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved` (any case), then `#N`, with an optional `:` after the keyword. A list works: `fixes #3, #4 and #5`. They count in the title, the description and the commit messages, not in notes. Closing the merge request without merging resolves nothing.
-- **Any `#N`** in the title, description, notes or commit messages shows the merge request on the issue (`ermite issue show`, the API `references`), with its state and whether it closes the issue.
+- **Any `#N`** in the title, description, notes or commit messages shows the merge request on the issue (`ermite issue show`, the API `references`), with its state and whether it resolves the issue on merge.
-- A closed issue records the merge request that closed it ("closed by !N"). Reopening or closing by hand clears it.
+- A merge-resolved issue records the merge request that resolved it ("resolved by !N"). Reopening clears it.
 - The links are recomputed whenever the merge request changes (a note added, edited or deleted, a push to its branch, a merge), so removing a mention removes the link.
 - Words glued to the number (`abc#3`), `&#39;` and `##3` are not references. Code spans are not skipped.
-Limits: the 100 most recent commits of the merge request, 16 KiB of each text, 100 merge requests listed per issue. Only numbers of existing issues are linked: a mention of a number that does not exist yet is not filled in later. With issues `off`, nothing is closed.
+Limits: the 100 most recent commits of the merge request, 16 KiB of each text, 100 merge requests listed per issue. Only numbers of existing issues are linked: a mention of a number that does not exist yet is not filled in later. With issues `off`, nothing is resolved.
 ## Inbox

M docs/merge-requests.md +5 -1


@@ -8,7 +8,7 @@ ermite mr show myrepo 1 --diff
8	8		ermite mr merge myrepo 1 --head <commit> [--mode fast-forward\|squash\|merge] [--delete-branch]
9	9		```
10	10
11		-	Naming an issue with `#N` links it, and `Fixes #N` closes it on merge: see [issues](issues.md#merge-request-links).
	11	+	Naming an issue with `#N` links it, and `Fixes #N` resolves it on merge: see [issues](issues.md#merge-request-links).
12	12
13	13		`ermite mr create` and `ermite mr close` print a confirmation followed by the full
14	14		merge request web URL on its own line. With `--json`, merge request objects

@@ -16,6 +16,10 @@ merge request web URL on its own line. With `--json`, merge request objects
16	16
17	17		A draft cannot merge. `ermite mr ready <repo> <n>` removes the `WIP:` or `[WIP]` title prefix; it needs `mr:write` and an open draft.
18	18
	19	+	## Linked issues and history
	20	+
	21	+	The web Issues rail lists current linked issues with their state and a resolves marker for closing references. Links lead to the issue. The conversation includes timestamped system rows for references and resolutions, interleaved with general comments. Removing a reference removes its current link, not its history; historical rows may name issues no longer in the rail.
	22	+
19	23		## Merge modes
20	24
21	25		\| Mode \| Result \| Needs \|

 ermite mr merge myrepo 1 --head <commit> [--mode fast-forward|squash|merge] [--delete-branch]
 ```
-Naming an issue with `#N` links it, and `Fixes #N` closes it on merge: see [issues](issues.md#merge-request-links).
+Naming an issue with `#N` links it, and `Fixes #N` resolves it on merge: see [issues](issues.md#merge-request-links).
 `ermite mr create` and `ermite mr close` print a confirmation followed by the full
 merge request web URL on its own line. With `--json`, merge request objects
 A draft cannot merge. `ermite mr ready <repo> <n>` removes the `WIP:` or `[WIP]` title prefix; it needs `mr:write` and an open draft.
+## Linked issues and history
+The web Issues rail lists current linked issues with their state and a **resolves** marker for closing references. Links lead to the issue. The conversation includes timestamped system rows for references and resolutions, interleaved with general comments. Removing a reference removes its current link, not its history; historical rows may name issues no longer in the rail.
 ## Merge modes
 | Mode | Result | Needs |