turbo-editors/turbo-core · release-the-library.md

⑂ 28d59854361aeda8541d853093e732126f3d7bff

release-the-library.md · 95 lines · 3.7 KBmarkdown    Blame HistoryRaw
   1# How to release the library
3This guide shows how to publish a version of turbo-core that the editors can depend on. It assumes commit access to the repository.
5turbo-core is a Go module with no binary and no release artefacts: publishing it is tagging it. `01-release.tag.sh` does the whole thing.
9### 1. Say which version
11Create `release.env` — it is gitignored, because a release token belongs in one too:
14TAG="v0.1.0"
15ABOUT="The Turbo editor library"
18### 2. Run the script
21./01-release.tag.sh
24It runs `make check`, refuses a tag already taken here 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.
26That 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.
28### 3. Create the release page
30The tag is enough for `go get`; this adds the page a person reads.
33./02-release.publish.sh --dry-run    # show the request, send nothing
34./02-release.publish.sh              # create it
37It needs `curl` and `jq`, `OWNER` and `REPO` in `release.env`, and a Codeberg application token in `turbo-core.token.env` — a separate file so `release.env` can be shown to somebody without leaking it. Both are covered by `*.env` in `.gitignore`.
39The notes it writes are `ABOUT`, the one line that installs the module, and links to the documentation **at that tag** rather than at the branch.
41There is no `03` or `04` here. Those build and attach binaries in the editors; a library has none — its artefact is the tag.
43### 4. Point the editors at it
45One editor at a time, running its suite before moving to the next:
48go mod edit -require=codeberg.org/turbo-editors/turbo-core@v0.1.0
49go mod edit -dropreplace=codeberg.org/turbo-editors/turbo-core
50go mod tidy
51
54Every editor depends on the same library, so a change that breaks one usually breaks the rest — finding that out three times in a row is cheaper than finding it out in a release.
56## Variants
58### You would rather do it by hand
61
62git push origin main
63git tag -a v0.1.0 -m "The Turbo editor library"
64git push origin v0.1.0
67Push the branch **before** the tag, for the reason above.
69### You are developing across the three repositories
71Since v0.1.0 the editors depend on the published module and carry no `replace`, so a library change is invisible to them until it is published. Do not publish to find out whether it works — use a workspace, which changes no tracked file:
74cd turbo-go
75go work init . ../turbo-core
78[Test without publishing](test-without-publishing.md) covers this properly, including how to tell whether it took effect and how to test the published shape once you are ready.
80### The change is not backwards compatible
82Say so in the tag message and bump the minor version — the module is below v1, so a minor bump is the signal available. The editors pin an exact version, so nothing moves until somebody edits a `go.mod`.
84### You need to move a tag you have already pushed
86You do not. Several editors may pin it and the module proxy caches what it fetched, so the script refuses. Bump `TAG` instead.
88## What to watch out for
90The script runs `make check`, and the suite it runs includes tests that run *this script* against a throwaway clone. They skip themselves when `TURBO_CORE_RELEASING` is set, which the script exports before calling make. Removing that line makes a release recurse until something runs out.
92## See also
94- Releasing an editor: each editor's `how-to/make-a-release.md`
95- What the tests cover: [Run the tests](run-the-tests.md)

🛟 Updated. 28d5985 k33g 18h ago	1	# How to release the library
	2
	3	This guide shows how to publish a version of turbo-core that the editors can depend on. It assumes commit access to the repository.
	4
	5	turbo-core is a Go module with no binary and no release artefacts: publishing it is tagging it. `01-release.tag.sh` does the whole thing.
	6
	7	## Steps
	8
	9	### 1. Say which version
	10
	11	Create `release.env` — it is gitignored, because a release token belongs in one too:
	12
	13	```sh
	14	TAG="v0.1.0"
	15	ABOUT="The Turbo editor library"
	16	```
	17
	18	### 2. Run the script
	19
	20	```bash
	21	./01-release.tag.sh
	22	```
	23
	24	It runs `make check`, refuses a tag already taken here 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.
	25
	26	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.
	27
	28	### 3. Create the release page
	29
	30	The tag is enough for `go get`; this adds the page a person reads.
	31
	32	```bash
	33	./02-release.publish.sh --dry-run # show the request, send nothing
	34	./02-release.publish.sh # create it
	35	```
	36
	37	It needs `curl` and `jq`, `OWNER` and `REPO` in `release.env`, and a Codeberg application token in `turbo-core.token.env` — a separate file so `release.env` can be shown to somebody without leaking it. Both are covered by `*.env` in `.gitignore`.
	38
	39	The notes it writes are `ABOUT`, the one line that installs the module, and links to the documentation at that tag rather than at the branch.
	40
	41	There is no `03` or `04` here. Those build and attach binaries in the editors; a library has none — its artefact is the tag.
	42
	43	### 4. Point the editors at it
	44
	45	One editor at a time, running its suite before moving to the next:
	46
	47	```bash
	48	go mod edit -require=codeberg.org/turbo-editors/turbo-core@v0.1.0
	49	go mod edit -dropreplace=codeberg.org/turbo-editors/turbo-core
	50	go mod tidy
	51	make test
	52	```
	53
	54	Every editor depends on the same library, so a change that breaks one usually breaks the rest — finding that out three times in a row is cheaper than finding it out in a release.
	55
	56	## Variants
	57
	58	### You would rather do it by hand
	59
	60	```bash
	61	make check
	62	git push origin main
	63	git tag -a v0.1.0 -m "The Turbo editor library"
	64	git push origin v0.1.0
65	```
66
67	Push the branch before the tag, for the reason above.
68
69	### You are developing across the three repositories
70
71	Since v0.1.0 the editors depend on the published module and carry no `replace`, so a library change is invisible to them until it is published. Do not publish to find out whether it works — use a workspace, which changes no tracked file:
72
73	```bash
74	cd turbo-go
75	go work init . ../turbo-core
76	```
77
78	[Test without publishing](test-without-publishing.md) covers this properly, including how to tell whether it took effect and how to test the published shape once you are ready.
79
80	### The change is not backwards compatible
81
82	Say so in the tag message and bump the minor version — the module is below v1, so a minor bump is the signal available. The editors pin an exact version, so nothing moves until somebody edits a `go.mod`.
83
84	### You need to move a tag you have already pushed
85
86	You do not. Several editors may pin it and the module proxy caches what it fetched, so the script refuses. Bump `TAG` instead.
87
88	## What to watch out for
89
90	The script runs `make check`, and the suite it runs includes tests that run this script against a throwaway clone. They skip themselves when `TURBO_CORE_RELEASING` is set, which the script exports before calling make. Removing that line makes a release recurse until something runs out.
91
92	## See also
93
94	- Releasing an editor: each editor's `how-to/make-a-release.md`
95	- What the tests cover: [Run the tests](run-the-tests.md)