From: Anderson A. Giacomolli Date: Fri, 6 Nov 2026 14:00:38 +0000 (-0300) Subject: Track issues with git-bug X-Git-Url: http://git.giacomolli.uk/onechat/commitdiff_plain/0dc5d2bd42abc8be2cb23bfec06661275a08f516?ds=inline Track issues with git-bug Issues live in git-bug, inside the Git repository, so they work offline and travel with the code through git bug push and pull. They are not files in the checkout, so they stay out of diffs, formatters, and the rule that files describe only the current state. The development shell supplies git-bug. The issues skill tells agents how to read and write issues, and warns that the -F option drops every line that starts with "#". Commit messages now refer to an issue with an Issue trailer that holds its git-bug ID, because there are no issue URLs to link. git-bug has no links between issues, so relations are Parent and Depends-on trailers at the end of the body, as in a commit message. git interpret-trailers can read them, and a search for an issue ID finds the issues that refer to it. --- diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md index 6676a85..7e1f657 100644 --- a/.agents/skills/commit/SKILL.md +++ b/.agents/skills/commit/SKILL.md @@ -44,9 +44,10 @@ description: Commit procedure and message rules. Use for every commit. ## Trailers -- When the change belongs to an issue, end the message with one `Link:` - trailer to that issue. Add it with `git commit --trailer`. Never use a - closing keyword such as "Fixes" or "Closes". +- When the change belongs to an issue, end the message with one `Issue:` + trailer with the git-bug ID of that issue. Add it with + `git commit --trailer`. Never use a closing keyword such as "Fixes" or + "Closes". - Link the bug report when a change fixes a reported bug. - Do not add an AI tool as co-author. Do not add attribution trailers. diff --git a/.agents/skills/issues/SKILL.md b/.agents/skills/issues/SKILL.md new file mode 100644 index 0000000..225d95c --- /dev/null +++ b/.agents/skills/issues/SKILL.md @@ -0,0 +1,60 @@ +--- +name: issues +description: Read and write issues with git-bug. Use for any issue work. +--- + +# Issues + +Issues live in git-bug, inside the Git repository, not in files. The +`overview` issue lists the phases and the open decisions. Run the +commands in the Nix development shell. + +## Read + +- List the open issues with `git bug bug status:open`. +- Read an issue and all its comments with `git bug bug show ID` before + you start work on it. + +## Write + +- Give the title and the body with `-t` and `-m`. Do not use `-F`: it + drops every line that starts with `#`, so Markdown headings are lost. +- Write the title like a commit subject: 50 characters or fewer, in the + imperative mood, with no final period. +- Write the body in Markdown. State the result for the user, the scope, + and how to check it. +- Add a comment with `git bug bug comment new ID -m TEXT` for progress + that matters: decisions made with the user, measurements, and checks + that could not run. +- Close an issue with `git bug bug status close ID` only when its check + passes. +- Label a phase `phase`, an open question `decision`, and the plan + `overview`, with `git bug bug label new ID LABEL`. + +## Relations + +git-bug has no links between issues. Write them as trailers in the last +paragraph of the body, one per line, as in a commit message: + +- `Parent: ID` names the issue that this issue belongs to. A child has + one parent. +- `Depends-on: ID, ID` names the issues that must be done first. +- A parent lists the IDs of its children in its body. + +`git interpret-trailers --parse` reads the trailers of a body. + +Find the issues that relate to an issue with `git bug bug ID`. The +search finds every issue that mentions the ID, so read the trailers of +each match. Do not search for more than one word: git-bug finds issues +that match any of the words, and it reads `Parent:` as a query +qualifier. Nothing checks the trailers. Before you close a parent, make +sure that its children are closed. + +Push the issues with `git bug push` when the repository has a remote. + +This example creates an issue: + +```sh +git bug bug new --non-interactive -t 'Decide the root wake interval' \ + -m "$(cat body.md)" +``` diff --git a/AGENTS.md b/AGENTS.md index 07a8f57..bfeccf2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,7 @@ Read the `SKILL.md` of a skill before you start the task that it covers: | Write or change documentation or prose comments | `.agents/skills/docs` | | Format and check the repository | `.agents/skills/check` | | Make any commit | `.agents/skills/commit` | +| Read or write an issue | `.agents/skills/issues` | ## Rules diff --git a/nix/devshell.nix b/nix/devshell.nix index 9ec0209..fdf65e9 100644 --- a/nix/devshell.nix +++ b/nix/devshell.nix @@ -2,6 +2,7 @@ pkgs.mkShell { packages = with pkgs; [ git + git-bug go gofumpt golangci-lint