docs(issues): describe resolution and linked issue history
- commit
- 8915b454c41d0ef2b6db376aadc822a5277d659d
- author
- brice · · 2026-10-22 18:14 UTC
- committer
- brice · · 2026-10-22 18:41 UTC
- parent
- a8cc2eb
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
2 files · +22 -7
M docs/issues.md +17 -6
| @@ -1,19 +1,30 @@ | |||
| 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 | ``` | |
| 14 | 15 | ||
| 15 | 16 | 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. | |
| 16 | 17 | ||
| 18 | + | ## States and history | |
| 19 | + | ||
| 20 | + | - **Open**: work remains. | |
| 21 | + | - **Closed**: closed without being resolved. | |
| 22 | + | - **Resolved**: fixed, either with `ermite issue resolve <repo> <n>` or by merging a closing reference. | |
| 23 | + | ||
| 24 | + | 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. | |
| 25 | + | ||
| 26 | + | 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. | |
| 27 | + | ||
| 17 | 28 | ## The `issues` setting | |
| 18 | 29 | ||
| 19 | 30 | `ermite repo edit <repo> --issues off|owner|public`, shown by `repo show` (JSON field `issues`): | |
| @@ -38,13 +49,13 @@ Merge requests and issues of a repository draw `#n` from one sequence, so a numb | |||
| 38 | 49 | ||
| 39 | 50 | A merge request and the issues of its repository are linked by `#N` in its text: | |
| 40 | 51 | ||
| 41 | - | - **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. | |
| 42 | - | - **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. | |
| 43 | - | - A closed issue records the merge request that closed it ("closed by !N"). Reopening or closing by hand clears it. | |
| 52 | + | - **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. | |
| 53 | + | - **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. | |
| 54 | + | - A merge-resolved issue records the merge request that resolved it ("resolved by !N"). Reopening clears it. | |
| 44 | 55 | - 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. | |
| 45 | 56 | - Words glued to the number (`abc#3`), `'` and `##3` are not references. Code spans are not skipped. | |
| 46 | 57 | ||
| 47 | - | 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. | |
| 58 | + | 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. | |
| 48 | 59 | ||
| 49 | 60 | ## Inbox | |
| 50 | 61 | ||
| @@ -1,19 +1,30 @@ | |||||
| 1 | # Issues | 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 | ```sh | 5 | ```sh | ||
| 6 | ermite repo edit myrepo --issues owner | 6 | ermite repo edit myrepo --issues owner | ||
| 7 | ermite issue create myrepo --title "Crash on start" --body "It crashes." | 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 | ermite issue show myrepo 2 | 9 | ermite issue show myrepo 2 | ||
| 10 | ermite issue comment myrepo 2 -m "Reproduced." | 10 | ermite issue comment myrepo 2 -m "Reproduced." | ||
| 11 | + | ermite issue resolve myrepo 2 | |||
| 11 | ermite issue close myrepo 2 | 12 | ermite issue close myrepo 2 | ||
| 12 | ermite issue reopen myrepo 2 | 13 | ermite issue reopen myrepo 2 | ||
| 13 | ``` | 14 | ``` | ||
| 14 | 15 | ||||
| 15 | 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. | 16 | 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. | ||
| 16 | 17 | ||||
| 18 | + | ## States and history | |||
| 19 | + | ||||
| 20 | + | - **Open**: work remains. | |||
| 21 | + | - **Closed**: closed without being resolved. | |||
| 22 | + | - **Resolved**: fixed, either with `ermite issue resolve <repo> <n>` or by merging a closing reference. | |||
| 23 | + | ||||
| 24 | + | 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. | |||
| 25 | + | ||||
| 26 | + | 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. | |||
| 27 | + | ||||
| 17 | ## The `issues` setting | 28 | ## The `issues` setting | ||
| 18 | 29 | ||||
| 19 | `ermite repo edit <repo> --issues off|owner|public`, shown by `repo show` (JSON field `issues`): | 30 | `ermite repo edit <repo> --issues off|owner|public`, shown by `repo show` (JSON field `issues`): | ||
| @@ -38,13 +49,13 @@ Merge requests and issues of a repository draw `#n` from one sequence, so a numb | |||||
| 38 | 49 | ||||
| 39 | A merge request and the issues of its repository are linked by `#N` in its text: | 50 | A merge request and the issues of its repository are linked by `#N` in its text: | ||
| 40 | 51 | ||||
| 41 | - | - **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. | 52 | + | - **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. |
| 42 | - | - **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. | 53 | + | - **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. |
| 43 | - | - A closed issue records the merge request that closed it ("closed by !N"). Reopening or closing by hand clears it. | 54 | + | - A merge-resolved issue records the merge request that resolved it ("resolved by !N"). Reopening clears it. |
| 44 | - 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. | 55 | - 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. | ||
| 45 | - Words glued to the number (`abc#3`), `'` and `##3` are not references. Code spans are not skipped. | 56 | - Words glued to the number (`abc#3`), `'` and `##3` are not references. Code spans are not skipped. | ||
| 46 | 57 | ||||
| 47 | - | 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. | 58 | + | 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. |
| 48 | 59 | ||||
| 49 | ## Inbox | 60 | ## Inbox | ||
| 50 | 61 | ||||
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 | | |
| @@ -8,7 +8,7 @@ ermite mr show myrepo 1 --diff | |||||
| 8 | ermite mr merge myrepo 1 --head <commit> [--mode fast-forward|squash|merge] [--delete-branch] | 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 | `ermite mr create` and `ermite mr close` print a confirmation followed by the full | 13 | `ermite mr create` and `ermite mr close` print a confirmation followed by the full | ||
| 14 | merge request web URL on its own line. With `--json`, merge request objects | 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 | A draft cannot merge. `ermite mr ready <repo> <n>` removes the `WIP:` or `[WIP]` title prefix; it needs `mr:write` and an open draft. | 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 | ## Merge modes | 23 | ## Merge modes | ||
| 20 | 24 | ||||
| 21 | | Mode | Result | Needs | | 25 | | Mode | Result | Needs | | ||