vole
Clone
Read only, no credentials:
https://rodent.software/git/vole.git
Write over SSH with a registered key:
git clone ssh://git@0.0.0.0:2222/vole.git
A free and open-source forge that lives in your Git repo.
Number issues and change requests for human references
e05f1c48d4ee55635cd7b77889f0545137198106 · Keenan Nemetz · 13d ago · parent 41d1fee9
Number issues and change requests for human references A ULID is an unreadable handle, and the 8-character prefix the list showed is mostly timestamp: this repository's 27 issues shared seven distinct six-character prefixes and two pairs already collided at eight. The part people actually type carried almost no information. Issues and change requests now share one gap-free sequence (#1, #42, ...) derived from the creation order in the metadata branch's history, the way one forge counts both in a single run. The number is not stored. It is the rank of the entity's creation commit, so nothing is written when an entity is created, a repository needs no backfill, the same history gives the same numbers on every clone, and `vole admin index rebuild` reproduces them from git. A ULID stays the identity: paths, front matter, `closes:` and audit entries are unchanged, and data/index.db only caches the mapping so a page render does not walk history. Every id-taking command accepts a number, `#42` links in a body through a kind-agnostic /r/<repo>/n/42 route, and --closes resolves an alias to the ULID before writing. Closes #45
docs/issues.md +36−4
| @@ -36,6 +36,32 @@ Markdown body. Titles and other free text are always quoted, so characters like | |||
| 36 | 36 | An issue id is a 26-character ULID. It uses uppercase letters and digits, but not | |
| 37 | 37 | `I`, `L`, `O`, or `U`. A UUID will not work. | |
| 38 | 38 | ||
| 39 | ## Numbers | ||
| 40 | |||
| 41 | Nobody types 26 characters, so every issue and change request also has a small | ||
| 42 | number: `#1`, `#42`. Issues and change requests share one sequence, oldest first, | ||
| 43 | the way one forge counts both in a single run. | ||
| 44 | |||
| 45 | The number is **derived, not stored**. It is the position of the commit that | ||
| 46 | created the entity in the metadata branch's history. Nothing is added to the file, | ||
| 47 | no counter is kept, and there is nothing to migrate: an existing repository gets | ||
| 48 | its numbers the first time anyone asks. Two clones of the same history produce the | ||
| 49 | same numbers, and `vole admin index rebuild` reproduces them from git. | ||
| 50 | |||
| 51 | The ULID is still the identity — it is the path, the front matter's neighbour in | ||
| 52 | `closes:`, the thing in the commit messages — so a number is a convenience, not a | ||
| 53 | reference you should quote in a script. The one way to make one wrong is to rewrite | ||
| 54 | the branch history: an admin redaction force-push renumbers everything after the | ||
| 55 | commit it rewrote. | ||
| 56 | |||
| 57 | Every command that takes an id takes a number instead, with or without the `#`: | ||
| 58 | |||
| 59 | ```sh | ||
| 60 | vole issue show 42 | ||
| 61 | vole issue close '#42' | ||
| 62 | vole change show 1 | ||
| 63 | ``` | ||
| 64 | |||
| 39 | 65 | ## Writing an issue without the CLI | |
| 40 | 66 | ||
| 41 | 67 | ```sh | |
| @@ -81,12 +107,15 @@ vole issue assign 01M5JR2JK29KKMAA1T9MDNTPBP wilbur | |||
| 81 | 107 | vole issue unassign 01M5JR2JK29KKMAA1T9MDNTPBP wilbur | |
| 82 | 108 | vole issue close 01M5JR2JK29KKMAA1T9MDNTPBP | |
| 83 | 109 | vole issue reopen 01M5JR2JK29KKMAA1T9MDNTPBP | |
| 84 | vole issue list --state open -l bug --assignee wilbur --format '%(shortid) %(title)' | ||
| 110 | vole issue list --state open -l bug --assignee wilbur --format '%(number) %(title)' | ||
| 85 | 111 | vole issue show 01M5JR2JK29KKMAA1T9MDNTPBP # a prefix is enough | |
| 112 | vole issue show 42 # the number is enough | ||
| 86 | 113 | ``` | |
| 87 | 114 | ||
| 88 | `--format` understands `%(id)`, `%(shortid)`, `%(state)`, `%(author)`, `%(title)`, | ||
| 89 | `%(labels)`, `%(assignees)`, and `%(created)`. | ||
| 115 | `--format` understands `%(number)`, `%(id)`, `%(shortid)`, `%(state)`, `%(author)`, | ||
| 116 | `%(title)`, `%(labels)`, `%(assignees)`, and `%(created)`. `%(shortid)` is a | ||
| 117 | prefix of the ULID, which is mostly timestamp; `%(number)` is the alias people | ||
| 118 | read and quote. | ||
| 90 | 119 | ||
| 91 | 120 | The CLI commits and pushes for you. It uses the account your SSH key belongs to, | |
| 92 | 121 | not the name in `git config`. If you want to commit without pushing, add | |
| @@ -109,7 +138,10 @@ vole issue new --title "the docs page is blank" \ | |||
| 109 | 138 | - History on the `vole` branch must be linear. Merge commits are not allowed. | |
| 110 | 139 | - Force-pushing `vole` requires repository admin and is recorded in | |
| 111 | 140 | `data/audit.log`. It is meant for redaction, not normal work. | |
| 112 | - Writing `#<ulid>` in a body links to that issue. Commits that mention an id are | ||
| 141 | - Writing `#42` in a body links to that entity. Because one sequence holds both | ||
| 142 | kinds, the link goes through `/n/42`, and the server resolves it to the issue or | ||
| 143 | the change request that holds the number. `#<ulid>` links by id and is the form | ||
| 144 | that keeps working if history is ever rewritten. Commits that mention an id are | ||
| 113 | 145 | shown as backlinks on the issue page. | |
| 114 | 146 | - An assignee must be a valid account name: lowercase letters, digits, `-`, and | |
| 115 | 147 | `_`. The name is stored as written because account names are never reused. A | |