vole
Clone
Read only, no credentials:
https://rodent.software/vole.git
Write over SSH with a registered key:
git clone ssh://git@rodent.software: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
CONTRIBUTING.md +19−12
| @@ -35,13 +35,20 @@ GitHub, adapt it to the Vole workflow below or ask. | |||
| 35 | 35 | Read the open work first: | |
| 36 | 36 | ||
| 37 | 37 | ```sh | |
| 38 | ./vole issue list --state open --format '%(id) %(title)' | ||
| 39 | ./vole issue list --state open -l security --format '%(id) %(title)' | ||
| 40 | ./vole issue show <full-id> | ||
| 38 | ./vole issue list --state open --format '%(number) %(title)' | ||
| 39 | ./vole issue list --state open -l security --format '%(number) %(title)' | ||
| 40 | ./vole issue show <number> | ||
| 41 | 41 | ``` | |
| 42 | 42 | ||
| 43 | Use the **full 26-character ULID** in scripts and issue bodies. The | ||
| 44 | 8-character prefixes shown by `%(shortid)` can collide. | ||
| 43 | Read and quote the `#42` **number**: issues and change requests share one | ||
| 44 | sequence, and every command that takes an id takes the number, or a prefix of the | ||
| 45 | ULID that `%(id)` prints. | ||
| 46 | |||
| 47 | Use the **full 26-character ULID** when durability matters — a script, a commit | ||
| 48 | message, a file outside this workflow. The number is derived from the creation | ||
| 49 | order in the `vole` branch's history, so an admin redaction that rewrites that | ||
| 50 | history renumbers what came after it. The 8-character prefixes shown by | ||
| 51 | `%(shortid)` can also collide: they are mostly timestamp. | ||
| 45 | 52 | ||
| 46 | 53 | The CLI writes the `vole` metadata branch directly, so issue and comment writes | |
| 47 | 54 | need `maintain` access. A contributor without that role files issues and | |
| @@ -62,7 +69,7 @@ Conventions used in this repository: | |||
| 62 | 69 | - Prefix priority in the title when it applies: `P0:`, `P1:`, `P2:`. | |
| 63 | 70 | - Use lowercase labels with `-` or `_`, never spaces. | |
| 64 | 71 | - Include **why**, **scope/checklist**, and **acceptance criteria**. | |
| 65 | - Link related work with `#<full-ulid>` in the body. | ||
| 72 | - Link related work with `#42` in the body. | ||
| 66 | 73 | - Assign the issue to yourself if you are going to work on it. | |
| 67 | 74 | - Useful labels include `security`, `p0`, `p1`, `p2`, `bug`, `availability`, | |
| 68 | 75 | `auth`, `authz`, `ci`, `deployment`, `web`, `testing`, and `tracking`. | |
| @@ -98,7 +105,7 @@ Then open a Vole change request if the branch should be reviewed: | |||
| 98 | 105 | ||
| 99 | 106 | ```sh | |
| 100 | 107 | ./vole change new --title "..." --base main --head <branch> \ | |
| 101 | --closes <full-ulid> -F /tmp/change-body.md | ||
| 108 | --closes <issue-number> -F /tmp/change-body.md | ||
| 102 | 109 | ./vole change list --state open --format '%(id) %(title)' | |
| 103 | 110 | ./vole change show <full-id> | |
| 104 | 111 | ``` | |
| @@ -109,11 +116,11 @@ head no longer count, so the new tip needs its own approval and checks. You do n | |||
| 109 | 116 | need to run `change update --head` after every push; use it only to repoint an | |
| 110 | 117 | open request at a different branch, or at a bare commit. | |
| 111 | 118 | ||
| 112 | Link the issue with `--closes <full-ulid>` (repeatable) when the branch fixes | ||
| 113 | one. That field is what the request page shows and what landing the request | ||
| 114 | closes; `Fixes #<ulid>` in the description is only text. A link may be added or | ||
| 115 | replaced later with `./vole change update <full-id> --closes <full-ulid>` while | ||
| 116 | the request is open. | ||
| 119 | Link the issue with `--closes <issue-number>` (repeatable; a full ULID works too) | ||
| 120 | when the branch fixes one. That field is what the request page shows and what | ||
| 121 | landing the request closes; `Fixes #42` in the description is only text. A link may | ||
| 122 | be added or replaced later with `./vole change update <id> --closes <number>` | ||
| 123 | while the request is open. | ||
| 117 | 124 | ||
| 118 | 125 | Important differences from a GitHub-style forge: | |
| 119 | 126 | ||