turbo-editors/turbo-golo · versioning.md

⑂ main

versioning.md · 153 lines · 6.8 KBmarkdown    Blame HistoryRaw
📦 Turbo Golo   1# Reference: the version number
3> Neutral description of where the version Turbo Golo reports comes from, and what each way of building it produces.
5## Where the number comes from
7Three sources, consulted in this order. The first that answers wins.
9| Order | Source | Set by |
10| --- | --- | --- |
11| 1 | Linker stamps | `make build`, `make install`, `scripts/install.sh`, `03-build-releases.sh` |
12| 2 | Go build information | The Go tool, automatically |
13| 3 | `unknown` | Nothing — the value reported when no source could name the build |
15There is **no version constant in the source**. A number written into a `.go` file has to be edited as part of releasing, and is wrong the moment someone forgets.
17## Linker stamps
19Three package-level variables in turbo-core's `version` package — the library every Turbo editor shares, so the paths name `turbo-core`, not this repository — set with `-ldflags -X`.
21| Variable | Filled from | Example |
22| --- | --- | --- |
23| `stamp` | `git describe --tags --dirty` | `v0.1.0-14-g88a4c38` |
24| `commit` | `git rev-parse --short HEAD` | `88a4c38` |
25| `built` | `date -u +%Y-%m-%dT%H:%M:%SZ` | `2026-09-14T18:04:05Z` |
28go build -ldflags "\
29  -X 'rickub.com/turbo-editors/turbo-core/version.stamp=v0.1.0' \
30  -X 'rickub.com/turbo-editors/turbo-core/version.commit=88a4c38' \
31  -X 'rickub.com/turbo-editors/turbo-core/version.built=2026-09-14T18:04:05Z'" .
34A leading `v` is dropped for display: the tag is `v0.1.0`, the About box says `0.1.0`.
36## Go build information
38Read from `runtime/debug.ReadBuildInfo()` when nothing was stamped.
40| Field read | Used for |
41| --- | --- |
42| `Main.Version` | The number, unless it is empty, `(devel)`, or a pseudo-version |
43| `vcs.revision` | The commit, abbreviated to seven characters |
44| `vcs.modified` | Whether `-dirty` is appended |
46`vcs.time` is **not** used. It records when the commit was made, not when the binary was linked, so reporting it as a build date would be wrong on every binary built later than its own commit.
48A **pseudo-version** — `v0.0.0-20260914120000-0123456789ab` for a module with no tag yet, `v0.1.1-0.20260914120000-0123456789ab` for a commit after one — is the Go tool naming a commit that no tag names. It is reported as `devel`, not shown as written: its `0.1.1` is a patch release that does not exist.
50## What each build reports
52| Built by | Number | Commit | Built |
53| --- | --- | --- | --- |
54| `make build`, `make install`, `scripts/install.sh` | `0.1.0-14-g88a4c38` | yes | yes |
55| The same, on a tagged commit | `0.1.0` | yes | yes |
56| The same, with uncommitted changes | `0.1.0-14-g88a4c38-dirty` | yes | yes |
57| The same, in a checkout with no tag at all | `devel` | yes | yes |
58| `03-build-releases.sh` | the `TAG` in `release.env`, whatever `git describe` says | yes | yes |
59| `go install rickub.com/turbo-editors/turbo-golo@v0.1.0` | `0.1.0` | no | no |
60| `go install rickub.com/turbo-editors/turbo-golo@latest`, before any tag exists | `devel` | no | no |
61| `go build .` in a checkout | `devel` | yes | no |
62| `go build .` in a checkout with uncommitted changes | `devel-dirty` | yes | no |
63| `go run .` | `unknown` | no | no |
64| A checkout with no git, and no stamps | `unknown` | no | no |
66Only the stamped rows can report a tag: the Go build system does not read git tags. Until Turbo Golo's first tag exists, `git describe` answers nothing and the Makefile stamps `devel` — a stamped `devel` still carries the commit and the build date.
68## Checked at build time
70A linker stamp is a string, and a wrong one is not an error. `-X` naming a symbol that does not exist links happily and stamps nothing; the binary then falls back to Go build information and reports a version the build never meant — often `devel`, on a binary attached to a release. Nothing but running the binary catches it, so every build that produces one runs it.
72`scripts/check-version.sh` is what runs.
74| Called by | On | A failure fails |
75| --- | --- | --- |
76| `make build` | `bin/turbo-golo`, with `$(VERSION)` and `$(COMMIT)` | the build |
77| `scripts/install.sh` | the staged binary, **before** it is installed | the install, leaving the binary already there untouched |
78| `03-build-releases.sh` | the one staged asset this machine can run, with the tag | the release build |
81scripts/check-version.sh bin/turbo-golo v0.1.0 88a4c38   # a stamped build
82scripts/check-version.sh bin/turbo-golo                  # nothing to expect
85| Arguments | Passes when |
86| --- | --- |
87| binary, version, commit | the reported number **equals** the version with its leading `v` dropped, and the commit appears in the output |
88| binary, version | the number equals it |
89| binary | the number is anything but `unknown` |
91The version comparison is an equality, not a search. `0.1.0` is a substring of `10.1.0`, and of a commit hash that happens to contain it; a stamp that is nearly right is exactly what this exists to catch.
93| Exit | Meaning |
94| --- | --- |
95| `0` | The binary reports what the build meant. The line it printed is echoed. |
96| `1` | It does not run, is not there, or reports something else. |
97| `2` | No binary was named. |
99## Where it is shown
101### `-version`
103One line, carrying every part that is known.
106Turbo Golo 0.1.0 (88a4c38, built 2026-09-14T18:04:05Z)
107Turbo Golo 0.1.0 (88a4c38)
108Turbo Golo 0.1.0
111### Help ▸ About
113One line per known fact. A fact the build did not record has **no line**, rather than an empty one.
116Turbo Golo 0.1.0
118A Turbo C-style editor for Golo,
119written in Go.
121Commit: 88a4c38
122Built:  2026-09-14 18:04 UTC
123Theme:  Turbo Classic
126`Built` is rendered in UTC as `YYYY-MM-DD HH:MM UTC`. A stamp that is not valid RFC 3339 is shown exactly as it was given, rather than dropped.
128### `make version`
130Prints what this checkout would stamp, without building.
133$ make version
134v0.1.0-14-g88a4c38 (88a4c38)
137### `make ldflags`
139Prints the linker flags a stamped build uses, so a script can reuse them instead of repeating the `-X` paths.
142$ make ldflags
143-X 'rickub.com/turbo-editors/turbo-core/version.stamp=v0.1.0' -X '….commit=7f8b36a' -X '….built=2026-09-14T19:02:03Z'
146`03-build-releases.sh` reads it for its cross-compiles, overriding the version with the tag it is releasing — `make ldflags VERSION=v0.1.0` — so the binaries say what the release says rather than what `git describe` says. A binary cross-compiled without it reports `devel`, whatever the release it is attached to says.
148## See also
150- Cutting a release so the number is right: [How to make a release](../how-to/make-a-release.md)
151- What `-version` is **not** for: it is written for a person. A script that needs the number should compare with `grep -F`, or ask git, rather than reading a field out of it.
152- Why there is no version constant: [Design decisions](../explanation/design-decisions.md#the-version-is-a-property-of-the-build-not-of-the-source)
153- The `-version` flag among the others: [Command line](cli.md)

📦 Turbo Golo d710c1b k33g 11h ago	1	# Reference: the version number
	2
	3	> Neutral description of where the version Turbo Golo reports comes from, and what each way of building it produces.
	4
	5	## Where the number comes from
	6
	7	Three sources, consulted in this order. The first that answers wins.
	8
	9	\| Order \| Source \| Set by \|
	10	\| --- \| --- \| --- \|
	11	\| 1 \| Linker stamps \| `make build`, `make install`, `scripts/install.sh`, `03-build-releases.sh` \|
	12	\| 2 \| Go build information \| The Go tool, automatically \|
	13	\| 3 \| `unknown` \| Nothing — the value reported when no source could name the build \|
	14
	15	There is no version constant in the source. A number written into a `.go` file has to be edited as part of releasing, and is wrong the moment someone forgets.
	16
	17	## Linker stamps
	18
	19	Three package-level variables in turbo-core's `version` package — the library every Turbo editor shares, so the paths name `turbo-core`, not this repository — set with `-ldflags -X`.
	20
	21	\| Variable \| Filled from \| Example \|
	22	\| --- \| --- \| --- \|
	23	\| `stamp` \| `git describe --tags --dirty` \| `v0.1.0-14-g88a4c38` \|
	24	\| `commit` \| `git rev-parse --short HEAD` \| `88a4c38` \|
	25	\| `built` \| `date -u +%Y-%m-%dT%H:%M:%SZ` \| `2026-09-14T18:04:05Z` \|
	26
	27	```sh
	28	go build -ldflags "\
	29	-X 'rickub.com/turbo-editors/turbo-core/version.stamp=v0.1.0' \
	30	-X 'rickub.com/turbo-editors/turbo-core/version.commit=88a4c38' \
	31	-X 'rickub.com/turbo-editors/turbo-core/version.built=2026-09-14T18:04:05Z'" .
	32	```
	33
	34	A leading `v` is dropped for display: the tag is `v0.1.0`, the About box says `0.1.0`.
	35
	36	## Go build information
	37
	38	Read from `runtime/debug.ReadBuildInfo()` when nothing was stamped.
	39
	40	\| Field read \| Used for \|
	41	\| --- \| --- \|
	42	\| `Main.Version` \| The number, unless it is empty, `(devel)`, or a pseudo-version \|
	43	\| `vcs.revision` \| The commit, abbreviated to seven characters \|
	44	\| `vcs.modified` \| Whether `-dirty` is appended \|
	45
	46	`vcs.time` is not used. It records when the commit was made, not when the binary was linked, so reporting it as a build date would be wrong on every binary built later than its own commit.
	47
	48	A pseudo-version — `v0.0.0-20260914120000-0123456789ab` for a module with no tag yet, `v0.1.1-0.20260914120000-0123456789ab` for a commit after one — is the Go tool naming a commit that no tag names. It is reported as `devel`, not shown as written: its `0.1.1` is a patch release that does not exist.
	49
	50	## What each build reports
	51
	52	\| Built by \| Number \| Commit \| Built \|
	53	\| --- \| --- \| --- \| --- \|
	54	\| `make build`, `make install`, `scripts/install.sh` \| `0.1.0-14-g88a4c38` \| yes \| yes \|
	55	\| The same, on a tagged commit \| `0.1.0` \| yes \| yes \|
	56	\| The same, with uncommitted changes \| `0.1.0-14-g88a4c38-dirty` \| yes \| yes \|
	57	\| The same, in a checkout with no tag at all \| `devel` \| yes \| yes \|
	58	\| `03-build-releases.sh` \| the `TAG` in `release.env`, whatever `git describe` says \| yes \| yes \|
	59	\| `go install rickub.com/turbo-editors/turbo-golo@v0.1.0` \| `0.1.0` \| no \| no \|
	60	\| `go install rickub.com/turbo-editors/turbo-golo@latest`, before any tag exists \| `devel` \| no \| no \|
	61	\| `go build .` in a checkout \| `devel` \| yes \| no \|
	62	\| `go build .` in a checkout with uncommitted changes \| `devel-dirty` \| yes \| no \|
	63	\| `go run .` \| `unknown` \| no \| no \|
	64	\| A checkout with no git, and no stamps \| `unknown` \| no \| no \|
65
66	Only the stamped rows can report a tag: the Go build system does not read git tags. Until Turbo Golo's first tag exists, `git describe` answers nothing and the Makefile stamps `devel` — a stamped `devel` still carries the commit and the build date.
67
68	## Checked at build time
69
70	A linker stamp is a string, and a wrong one is not an error. `-X` naming a symbol that does not exist links happily and stamps nothing; the binary then falls back to Go build information and reports a version the build never meant — often `devel`, on a binary attached to a release. Nothing but running the binary catches it, so every build that produces one runs it.
71
72	`scripts/check-version.sh` is what runs.
73
74	\| Called by \| On \| A failure fails \|
75	\| --- \| --- \| --- \|
76	\| `make build` \| `bin/turbo-golo`, with `$(VERSION)` and `$(COMMIT)` \| the build \|
77	\| `scripts/install.sh` \| the staged binary, before it is installed \| the install, leaving the binary already there untouched \|
78	\| `03-build-releases.sh` \| the one staged asset this machine can run, with the tag \| the release build \|
79
80	```sh
81	scripts/check-version.sh bin/turbo-golo v0.1.0 88a4c38 # a stamped build
82	scripts/check-version.sh bin/turbo-golo # nothing to expect
83	```
84
85	\| Arguments \| Passes when \|
86	\| --- \| --- \|
87	\| binary, version, commit \| the reported number equals the version with its leading `v` dropped, and the commit appears in the output \|
88	\| binary, version \| the number equals it \|
89	\| binary \| the number is anything but `unknown` \|
90
91	The version comparison is an equality, not a search. `0.1.0` is a substring of `10.1.0`, and of a commit hash that happens to contain it; a stamp that is nearly right is exactly what this exists to catch.
92
93	\| Exit \| Meaning \|
94	\| --- \| --- \|
95	\| `0` \| The binary reports what the build meant. The line it printed is echoed. \|
96	\| `1` \| It does not run, is not there, or reports something else. \|
97	\| `2` \| No binary was named. \|
98
99	## Where it is shown
100
101	### `-version`
102
103	One line, carrying every part that is known.
104
105	```
106	Turbo Golo 0.1.0 (88a4c38, built 2026-09-14T18:04:05Z)
107	Turbo Golo 0.1.0 (88a4c38)
108	Turbo Golo 0.1.0
109	```
110
111	### Help ▸ About
112
113	One line per known fact. A fact the build did not record has no line, rather than an empty one.
114
115	```
116	Turbo Golo 0.1.0
117
118	A Turbo C-style editor for Golo,
119	written in Go.
120
121	Commit: 88a4c38
122	Built: 2026-09-14 18:04 UTC
123	Theme: Turbo Classic
124	```
125
126	`Built` is rendered in UTC as `YYYY-MM-DD HH:MM UTC`. A stamp that is not valid RFC 3339 is shown exactly as it was given, rather than dropped.
127
128	### `make version`
129
130	Prints what this checkout would stamp, without building.
131
132	```
133	$ make version
134	v0.1.0-14-g88a4c38 (88a4c38)
135	```
136
137	### `make ldflags`
138
139	Prints the linker flags a stamped build uses, so a script can reuse them instead of repeating the `-X` paths.
140
141	```
142	$ make ldflags
143	-X 'rickub.com/turbo-editors/turbo-core/version.stamp=v0.1.0' -X '….commit=7f8b36a' -X '….built=2026-09-14T19:02:03Z'
144	```
145
146	`03-build-releases.sh` reads it for its cross-compiles, overriding the version with the tag it is releasing — `make ldflags VERSION=v0.1.0` — so the binaries say what the release says rather than what `git describe` says. A binary cross-compiled without it reports `devel`, whatever the release it is attached to says.
147
148	## See also
149
150	- Cutting a release so the number is right: [How to make a release](../how-to/make-a-release.md)
151	- What `-version` is not for: it is written for a person. A script that needs the number should compare with `grep -F`, or ask git, rather than reading a field out of it.
152	- Why there is no version constant: [Design decisions](../explanation/design-decisions.md#the-version-is-a-property-of-the-build-not-of-the-source)
153	- The `-version` flag among the others: [Command line](cli.md)