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.

Blame · docs/releases.md

Line attribution on main · 130 line(s)

View file History

520470e1 Keenan Nemetz 16d ago	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
ec343013 Keenan Nemetz 15d ago	27	## Create a release in the browser
	28
	29	A repository maintainer can create the same annotated tag from **Releases → New
	30	release**: choose a tag name, a target branch or commit, and write the notes. The
	31	notes become the tag message and the tagger is the account that submitted the
	32	form. Edit notes changes the message of an annotated tag while the release has
	33	no files attached; once an artifact is published the release is immutable, and
	34	the web refuses the edit. Lightweight tags are never editable.
	35
520470e1 Keenan Nemetz 16d ago	36	## Download source archives
520470e1 Keenan Nemetz 16d ago	37
b7396a11 Keenan Nemetz 4h ago	38	The `/<repo>/releases` page lists every tag. A release page shows the notes, the
520470e1 Keenan Nemetz 16d ago	39	commits since the previous release, and two generated downloads:
	40
	41	```sh
b7396a11 Keenan Nemetz 4h ago	42	curl -O http://host/demo/releases/v1.0.0/archive.tar
b7396a11 Keenan Nemetz 4h ago	43	curl -OJ http://host/demo/releases/v1.0.0/archive.tar.gz
520470e1 Keenan Nemetz 16d ago	44	```
	45
	46	Vole builds the archives from the tagged tree when someone requests them, so they
	47	cannot go stale. The `ETag` is the tag's id, so repeat downloads get a `304`, and
	48	the same tag produces the same bytes on every instance.
	49
	50	If a repository tracks files with Git LFS, the release page shows a warning.
	51	`git archive` copies pointer files, not the files themselves.
	52
	53	## Attach release files
	54
	55	Binaries attach over SSH into the shared storage, and Vole records a pointer for
	56	them:
	57
	58	```sh
	59	vole release attach v1.0.0 dist/vole-linux-amd64 dist/vole-darwin-arm64
b7396a11 Keenan Nemetz 4h ago	60	curl -O http://host/demo/releases/v1.0.0/artifacts/vole-linux-amd64
520470e1 Keenan Nemetz 16d ago	61	sha256sum vole-linux-amd64
	62	```
	63
	64	Attach files after pushing the tag, not before. The pointer is what publishes the
	65	file, and Vole refuses a pointer whose file was never uploaded. That way a
	66	download link never points at nothing.
	67
	68	If you attach the same file twice, Vole stores one copy and the second upload
	69	transfers nothing. Downloads support `ETag`, `304`, `Content-Disposition:
	70	attachment`, and Range requests, so large files can resume. Files from a private
	71	repository return `404`.
	72
	73	## Releases do not change
	74
	75	Once a release has files attached, Vole refuses to move or delete that tag, remove
	76	a file, or point a file name at different bytes. A saved download keeps meaning
	77	what it meant.
	78
	79	You can add another file; that does not invalidate anything. An admin can repair a
	80	mistyped release, and the override is recorded in `data/audit.log`.
	81
3abbe749 Keenan Nemetz 16d ago	82	Release file pointers live on the `vole` branch, so `vole admin gc --dry-run` treats a
520470e1 Keenan Nemetz 16d ago	83	published release file as something to keep.
	84
	85	## Build a release in CI
	86
	87	A workflow can build and publish a release instead of attaching files by hand:
	88
	89	```yaml
	90	artifacts:
	91	- path: dist/*
	92	release: true
	93	```
	94
	95	The run records the same pointers that `vole release attach` writes, so the
	96	release page, download behavior, and immutability rules stay the same. See
70b70264 Keenan Nemetz 15d ago	97	[Workflows § Build a release](workflows.md#build-a-release).
122a697b Keenan Nemetz 10d ago	98
	99	## A bill of materials for each release
	100
	101	A release built by the workflow carries an SBOM: `vole-<version>.sbom.cdx.json`,
	102	in CycloneDX JSON, listed on the release page beside the packages and covered by
	103	`SHA256SUMS`.
	104
	105	It names every Go module the application links, with the version and hash that
	106	`go.sum` pins, the Go toolchain, and each module's licence as detected evidence
	107	rather than an asserted conclusion. That is what makes it useful for the question
	108	it exists to answer: an advisory names a module version, and the SBOM says whether
	109	the binary you downloaded contains it.
	110
	111	Two limits, stated so nobody reads more into it than is there:
	112
	113	- One file covers both architectures. The module graph is the same for
	114	`amd64` and `arm64`; only the compiled files differ. Check it with
	115	`GOOS=linux GOARCH=arm64 go list -deps ./cmd/vole`.
	116	- The system SQLite library is not a Go module. The SBOM names
	117	`github.com/mattn/go-sqlite3`, the binding the build links, not the
	118	`libsqlite3-0` version underneath it. That one comes from the package you
	119	installed: `dpkg -s vole` or `rpm -q --requires vole`.
	120
	121	To regenerate it for a tag you already have:
	122
	123	```sh
	124	go run github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.9.0 \
	125	app -json -noserial -std -licenses -main cmd/vole -output SBOM.cdx.json .
	126	```
	127
	128	The only field the tool takes from the clock is `metadata.timestamp`; the workflow
	129	replaces it with the tag's commit time, so building one tag twice produces the
	130	same file.