Update the issue-tracker doc for zfj's new close, reopen, label and pr commands #22

New issue

Closed

opened 2026-10-15 16:49:45 -05:00 by jeff · 1 comment

jeff commented

2026-10-15 16:49:45 -05:00

Owner

docs/agents/issue-tracker.md is written for zfj 0.4.0, and describes workarounds for gaps that zfj has since filled. These changes are on zfj's main (git.jcollie.dev/jeff/zfj, up to d8e4c7d) but not yet in a release. Update the doc once a zfj with them is what harrier's sessions run, and change "written for zfj 0.4.0" to that version.

What changed in zfj

issue close takes a comment (jeff/zfj#22): zfj issue close <n> -c "<why>", or -F <file>; either takes - for stdin. The comment is posted first, then the issue is closed. The doc's "close takes no comment, so leave the closing comment with issue comment first" can go.
issue reopen (jeff/zfj#23): zfj issue reopen <n> [-c <text> | -F <file>].
Label commands (jeff/zfj#24): zfj label list [--json] and zfj label create <name> -c <hex> [-d <description>] [--force] [--json]. create refuses a name that already exists (exit 2), since Forgejo would otherwise allow duplicates; --force updates the existing label's color and description instead. This replaces the op issueCreateLabel recipe.
issue view --web (jeff/zfj#26): -w/--web opens the issue in the browser.
Pull request commands (jeff/zfj#25):
- zfj pr view <n> [--comments] [--json | --web]
- zfj pr list [-s open|closed|all] [-l <label>]... [-A <author>] [-B <base>] [-H <head>] [--json]. Merged pull requests show as merged.
- zfj pr diff <n> [--patch]. This replaces the op repoGetPullRequestFiles recipe.
- zfj pr create -t <title> [-b <text> | -F <file>] [-B <base>] [-H <head>] [-l <label>]... [-a <user>].... The head defaults to the checked-out branch, as owner:branch in a fork's clone, and the base defaults to the repository's default branch.

What to change in `docs/agents/issue-tracker.md`

Close: use issue close <n> -c "...".
Add Reopen.
Create a label: use zfj label create.
Pull requests as a triage surface: "zfj has no pr commands" is no longer true. Point at pr view --comments --json, pr list and pr diff. The claim that comment, edit --add-label and close work on a PR's number has now been tested against Forgejo 16 in zfj's VM test, so "(view has been tried on one; the others use the same endpoints)" can be dropped.
Wayfinding Resolve: issue comment then issue close can become a single issue close <n> -c "<answer>".

`docs/agents/issue-tracker.md` is written for zfj 0.4.0, and describes workarounds for gaps that zfj has since filled. These changes are on zfj's `main` (git.jcollie.dev/jeff/zfj, up to d8e4c7d) but **not yet in a release**. Update the doc once a zfj with them is what harrier's sessions run, and change "written for zfj 0.4.0" to that version. ## What changed in zfj - **`issue close` takes a comment** (jeff/zfj#22): `zfj issue close <n> -c "<why>"`, or `-F <file>`; either takes `-` for stdin. The comment is posted first, then the issue is closed. The doc's "`close` takes no comment, so leave the closing comment with `issue comment` first" can go. - **`issue reopen`** (jeff/zfj#23): `zfj issue reopen <n> [-c <text> | -F <file>]`. - **Label commands** (jeff/zfj#24): `zfj label list [--json]` and `zfj label create <name> -c <hex> [-d <description>] [--force] [--json]`. `create` refuses a name that already exists (exit 2), since Forgejo would otherwise allow duplicates; `--force` updates the existing label's color and description instead. This replaces the `op issueCreateLabel` recipe. - **`issue view --web`** (jeff/zfj#26): `-w/--web` opens the issue in the browser. - **Pull request commands** (jeff/zfj#25): - `zfj pr view <n> [--comments] [--json | --web]` - `zfj pr list [-s open|closed|all] [-l <label>]... [-A <author>] [-B <base>] [-H <head>] [--json]`. Merged pull requests show as `merged`. - `zfj pr diff <n> [--patch]`. This replaces the `op repoGetPullRequestFiles` recipe. - `zfj pr create -t <title> [-b <text> | -F <file>] [-B <base>] [-H <head>] [-l <label>]... [-a <user>]...`. The head defaults to the checked-out branch, as `owner:branch` in a fork's clone, and the base defaults to the repository's default branch. ## What to change in `docs/agents/issue-tracker.md` - **Close**: use `issue close <n> -c "..."`. - Add **Reopen**. - **Create a label**: use `zfj label create`. - **Pull requests as a triage surface**: "zfj has no `pr` commands" is no longer true. Point at `pr view --comments --json`, `pr list` and `pr diff`. The claim that `comment`, `edit --add-label` and `close` work on a PR's number has now been tested against Forgejo 16 in zfj's VM test, so "(`view` has been tried on one; the others use the same endpoints)" can be dropped. - Wayfinding **Resolve**: `issue comment` then `issue close` can become a single `issue close <n> -c "<answer>"`.

jeff added the

needs-triage

label

2026-10-15 16:49:46 -05:00

jeff commented

2026-10-16 13:10:50 -05:00

Author

Owner

Done in 427e2f3: the doc is now written for zfj 0.5.0, with close/reopen taking a comment, label list/create, pr view/list/diff for triage, and Resolve as a single issue close -c. pr create and issue view --web were left out on purpose: harrier commits to main, and agents don't use a browser.

Done in 427e2f3: the doc is now written for zfj 0.5.0, with close/reopen taking a comment, label list/create, pr view/list/diff for triage, and Resolve as a single issue close -c. pr create and issue view --web were left out on purpose: harrier commits to main, and agents don't use a browser.

jeff closed this issue

2026-10-16 13:10:50 -05:00

jeff referenced this issue from a commit

2026-10-16 13:10:51 -05:00

Update the issue-tracker doc for zfj 0.5.0