turbo-editors/turbo-go · make-a-release.md

⑂ main

make-a-release.md · 103 lines · 5.4 KBmarkdown    Blame HistoryRaw
   1# How to make a release
3This guide shows how to cut a release so that the editor reports its own version correctly. It assumes you can push to the repository.
5## Check what you are about to release
8make version
12v0.1.0-14-g88a4c38 (88a4c38)
15Fourteen commits past `v0.1.0`. A `-dirty` on the end means you have uncommitted changes — commit or stash them first, or the release will carry that suffix for ever.
17
20git tag -a v0.2.0 -m "v0.2.0"
21git push origin v0.2.0
24The tag is what the version comes from, so it has to exist before you build anything you intend to hand out. Annotated (`-a`) rather than lightweight, because `git describe` prefers annotated tags.
26## Build the release binary
29
30./bin/turbo-go -version
34Turbo Go 0.2.0 (88a4c38, built 2026-08-31T18:04:05Z)
37No `-14-g…` suffix: you are exactly on the tag. That is what tells you the tag took.
39## Check the About box
41Start the editor and press `Alt-H`, then `A`.
44Turbo Go 0.2.0
46A Turbo C-style editor for Go,
47written in Go.
49Commit: 88a4c38
50Built:  2026-08-31 18:04 UTC
51Theme:  Turbo Classic
54## Or use the scripts and let the workflow publish
56That is the way a release is actually cut. Put the version and its one-line description in `release.env` — it is gitignored, so CI never sees it:
59TAG="v1.0.0"
60ABOUT="Turbo Go"
63Then run one script:
66./01-release.tag.sh
69It runs `make check`, refuses a tag already taken locally or on `origin`, refuses a `go.mod` carrying a `replace` directive, commits anything outstanding, pushes the branch, and only then tags and pushes the tag. That order matters: a tag pushed before the branch points at a commit the remote has never seen, and a tag created before a failed push is left behind for somebody to find.
71That is the last thing you run by hand. Pushing the tag starts `.github/workflows/release.yml`; follow it on the repository's Actions tab. It runs the suite, cross-compiles the binaries with `./02-build-releases.sh` — the same script you can run on your machine — and creates the release page with them: the tag's message, the `go install` line, links to the documentation **at that tag**, one binary per platform, the `SHA256SUMS` and the README that describes the downloads.
73The job publishes with its own `GITHUB_TOKEN`, which is the only credential Rickub's release API accepts — a personal token is refused. There is nothing to configure and no secret to keep, which is why the old `02-release.publish.sh` and `04-release.upload-binaries.sh` are gone.
75`02-build-releases.sh` cross-compiles every platform and **stamps `TAG` itself**, by overriding the Makefile's version: `make ldflags VERSION=v1.0.0`. The release *is* `v1.0.0`, so that is what its binaries say — whatever `git describe` would have answered, and whether or not the tag has been created yet. It then runs the staged binary for this machine and checks it reports the version, which is the only proof that what ships carries it.
77You can see what the workflow will publish without publishing anything, or build the binaries by hand:
80./02-build-releases.sh v1.0.0     # writes release/v1.0.0/, pushes nothing
83With no argument it reads `TAG` from `release.env`; the workflow has no `release.env`, so it passes the tag it was started by.
85The suite includes tests that run `01-release.tag.sh` against a throwaway clone. They skip themselves when `TURBO_GO_RELEASING` is set, which the script exports before calling `make check` — removing that line makes a release recurse until something runs out. The workflow sets the same variable for its own `go test` step.
87## Variants
89- **You install rather than distribute a binary.** `make install` and `scripts/install.sh` stamp the same way, so an installed editor names the commit it came from. There is nothing extra to do.
90- **Someone installs with `go install`.** `go install rickub.com/turbo-editors/turbo-go@v0.2.0` reports `0.2.0` from the module version, with no commit and no build date. That is the Go tool's own record; nothing needs stamping.
91- **You tagged the wrong commit.** If the tag has not been pushed, delete it (`git tag -d v1.0.0`), tag the right one, and rebuild. Once it is on `origin`, do not move it: the module proxy has cached `go install …@v1.0.0` and the release page already carries binaries with that number, which is why `01-release.tag.sh` refuses a tag that exists. Bump `TAG` and release again.
92- **About says `devel`.** The binary was built with a plain `go build .` rather than through `make`. Nothing is wrong with it; it simply has no tag stamped, because the Go build system does not read git tags. Use `make build`.
93- **About says `unknown`.** Nothing named the build at all — a `go run .`, or a build from a directory with no git history. Use `make build` from the checkout.
94- **You have no git at all**, having downloaded a source archive. `make build` still works and the binary reports `unknown`. Pass the version yourself if you need one:
96  go build -ldflags "-X 'rickub.com/turbo-editors/turbo-core/version.stamp=v0.2.0'" -o bin/turbo-go .
99## See also
101- Every source of the number, and what each build reports: [The version number](../reference/versioning.md)
102- Why there is no version constant in the source: [Design decisions](../explanation/design-decisions.md#the-version-is-a-property-of-the-build-not-of-the-source)
103- Installing onto your PATH: [How to install and build Turbo Go](install.md)

📦 Turbo Go 3d7798b k33g 9h ago	1	# How to make a release
	2
	3	This guide shows how to cut a release so that the editor reports its own version correctly. It assumes you can push to the repository.
	4
	5	## Check what you are about to release
	6
	7	```sh
	8	make version
	9	```
	10
	11	```
	12	v0.1.0-14-g88a4c38 (88a4c38)
	13	```
	14
	15	Fourteen commits past `v0.1.0`. A `-dirty` on the end means you have uncommitted changes — commit or stash them first, or the release will carry that suffix for ever.
	16
	17	## Tag it
	18
	19	```sh
	20	git tag -a v0.2.0 -m "v0.2.0"
	21	git push origin v0.2.0
	22	```
	23
	24	The tag is what the version comes from, so it has to exist before you build anything you intend to hand out. Annotated (`-a`) rather than lightweight, because `git describe` prefers annotated tags.
	25
	26	## Build the release binary
	27
	28	```sh
	29	make build
	30	./bin/turbo-go -version
	31	```
	32
	33	```
	34	Turbo Go 0.2.0 (88a4c38, built 2026-08-31T18:04:05Z)
	35	```
	36
	37	No `-14-g…` suffix: you are exactly on the tag. That is what tells you the tag took.
	38
	39	## Check the About box
	40
	41	Start the editor and press `Alt-H`, then `A`.
	42
	43	```
	44	Turbo Go 0.2.0
	45
	46	A Turbo C-style editor for Go,
	47	written in Go.
	48
	49	Commit: 88a4c38
	50	Built: 2026-08-31 18:04 UTC
	51	Theme: Turbo Classic
	52	```
	53
	54	## Or use the scripts and let the workflow publish
	55
	56	That is the way a release is actually cut. Put the version and its one-line description in `release.env` — it is gitignored, so CI never sees it:
	57
	58	```sh
	59	TAG="v1.0.0"
	60	ABOUT="Turbo Go"
	61	```
	62
	63	Then run one script:
	64
65	```sh
66	./01-release.tag.sh
67	```
68
69	It runs `make check`, refuses a tag already taken locally or on `origin`, refuses a `go.mod` carrying a `replace` directive, commits anything outstanding, pushes the branch, and only then tags and pushes the tag. That order matters: a tag pushed before the branch points at a commit the remote has never seen, and a tag created before a failed push is left behind for somebody to find.
70
71	That is the last thing you run by hand. Pushing the tag starts `.github/workflows/release.yml`; follow it on the repository's Actions tab. It runs the suite, cross-compiles the binaries with `./02-build-releases.sh` — the same script you can run on your machine — and creates the release page with them: the tag's message, the `go install` line, links to the documentation at that tag, one binary per platform, the `SHA256SUMS` and the README that describes the downloads.
72
73	The job publishes with its own `GITHUB_TOKEN`, which is the only credential Rickub's release API accepts — a personal token is refused. There is nothing to configure and no secret to keep, which is why the old `02-release.publish.sh` and `04-release.upload-binaries.sh` are gone.
74
75	`02-build-releases.sh` cross-compiles every platform and stamps `TAG` itself, by overriding the Makefile's version: `make ldflags VERSION=v1.0.0`. The release is `v1.0.0`, so that is what its binaries say — whatever `git describe` would have answered, and whether or not the tag has been created yet. It then runs the staged binary for this machine and checks it reports the version, which is the only proof that what ships carries it.
76
77	You can see what the workflow will publish without publishing anything, or build the binaries by hand:
78
79	```sh
80	./02-build-releases.sh v1.0.0 # writes release/v1.0.0/, pushes nothing
81	```
82
83	With no argument it reads `TAG` from `release.env`; the workflow has no `release.env`, so it passes the tag it was started by.
84
85	The suite includes tests that run `01-release.tag.sh` against a throwaway clone. They skip themselves when `TURBO_GO_RELEASING` is set, which the script exports before calling `make check` — removing that line makes a release recurse until something runs out. The workflow sets the same variable for its own `go test` step.
86
87	## Variants
88
89	- You install rather than distribute a binary. `make install` and `scripts/install.sh` stamp the same way, so an installed editor names the commit it came from. There is nothing extra to do.
90	- Someone installs with `go install`. `go install rickub.com/turbo-editors/turbo-go@v0.2.0` reports `0.2.0` from the module version, with no commit and no build date. That is the Go tool's own record; nothing needs stamping.
91	- You tagged the wrong commit. If the tag has not been pushed, delete it (`git tag -d v1.0.0`), tag the right one, and rebuild. Once it is on `origin`, do not move it: the module proxy has cached `go install …@v1.0.0` and the release page already carries binaries with that number, which is why `01-release.tag.sh` refuses a tag that exists. Bump `TAG` and release again.
92	- About says `devel`. The binary was built with a plain `go build .` rather than through `make`. Nothing is wrong with it; it simply has no tag stamped, because the Go build system does not read git tags. Use `make build`.
93	- About says `unknown`. Nothing named the build at all — a `go run .`, or a build from a directory with no git history. Use `make build` from the checkout.
94	- You have no git at all, having downloaded a source archive. `make build` still works and the binary reports `unknown`. Pass the version yourself if you need one:
95	```sh
96	go build -ldflags "-X 'rickub.com/turbo-editors/turbo-core/version.stamp=v0.2.0'" -o bin/turbo-go .
97	```
98
99	## See also
100
101	- Every source of the number, and what each build reports: [The version number](../reference/versioning.md)
102	- Why there is no version constant in the source: [Design decisions](../explanation/design-decisions.md#the-version-is-a-property-of-the-build-not-of-the-source)
103	- Installing onto your PATH: [How to install and build Turbo Go](install.md)