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.

Docs: rewrite the README and organize the guides

520470e19cd906bd6fff987e2d132d793ce56486 · Keenan Nemetz · 16d ago · parent c5902451

Docs: rewrite the README and organize the guides

Replace the long README with a landing page, split feature details into focused guides, and remove the roadmap and spike notes. Update comments that referenced them.

docs/releases.md +88

@@ -0,0 +1,88 @@
	1	# Releases
	2
	3	A release should travel with the code. In Vole, it does: a release is a Git tag
	4	with a message. The message is the release notes, and the tagged code is the
	5	source. Both travel with every clone, so there is no separate release database to
	6	keep in sync.
	7
	8	## Create a release
	9
	10	```sh
	11	vole release create v1.0.0 -F notes.md
	12	git push --follow-tags
	13	```
	14
	15	Plain Git works the same way:
	16
	17	```sh
	18	git tag -a v1.0.0 -F notes.md
	19	git push --follow-tags
	20	```
	21
	22	Use an annotated tag (`git tag -a`). It has a message and a tagger. A lightweight
	23	tag appears in the release list for completeness, but it has no notes and cannot
	24	carry release files. `vole release create` refuses to overwrite an existing tag
	25	and tells you to choose a new name.
	26
	27	## Download source archives
	28
	29	The `/r/<repo>/releases` page lists every tag. A release page shows the notes, the
	30	commits since the previous release, and two generated downloads:
	31
	32	```sh
	33	curl -O http://host/r/demo/releases/v1.0.0/archive.tar
	34	curl -OJ http://host/r/demo/releases/v1.0.0/archive.tar.gz
	35	```
	36
	37	Vole builds the archives from the tagged tree when someone requests them, so they
	38	cannot go stale. The `ETag` is the tag's id, so repeat downloads get a `304`, and
	39	the same tag produces the same bytes on every instance.
	40
	41	If a repository tracks files with Git LFS, the release page shows a warning.
	42	`git archive` copies pointer files, not the files themselves.
	43
	44	## Attach release files
	45
	46	Binaries attach over SSH into the shared storage, and Vole records a pointer for
	47	them:
	48
	49	```sh
	50	vole release attach v1.0.0 dist/vole-linux-amd64 dist/vole-darwin-arm64
	51	curl -O http://host/r/demo/releases/v1.0.0/artifacts/vole-linux-amd64
	52	sha256sum vole-linux-amd64
	53	```
	54
	55	Attach files after pushing the tag, not before. The pointer is what publishes the
	56	file, and Vole refuses a pointer whose file was never uploaded. That way a
	57	download link never points at nothing.
	58
	59	If you attach the same file twice, Vole stores one copy and the second upload
	60	transfers nothing. Downloads support `ETag`, `304`, `Content-Disposition:
	61	attachment`, and Range requests, so large files can resume. Files from a private
	62	repository return `404`.
	63
	64	## Releases do not change
	65
	66	Once a release has files attached, Vole refuses to move or delete that tag, remove
	67	a file, or point a file name at different bytes. A saved download keeps meaning
	68	what it meant.
	69
	70	You can add another file; that does not invalidate anything. An admin can repair a
	71	mistyped release, and the override is recorded in `data/audit.log`.
	72
	73	Release file pointers live on the `vole` branch, so `vole gc --dry-run` treats a
	74	published release file as something to keep.
	75
	76	## Build a release in CI
	77
	78	A workflow can build and publish a release instead of attaching files by hand:
	79
	80	```yaml
	81	artifacts:
	82	- path: dist/*
	83	release: true
	84	```
	85
	86	The run records the same pointers that `vole release attach` writes, so the
	87	release page, download behavior, and immutability rules stay the same. See
	88	[CI § Build a release in CI](ci.md#build-a-release-in-ci).