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

⑂ v1.0.2

release-the-library.md · 106 lines · 5.1 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.
📦 Turbo Core   5turbo-core is a Go module with no binary: publishing it is tagging it, and the module proxy serves `go get …@TAG` the moment the tag is reachable. You run one script; pushing the tag starts a workflow that does the rest.
   6
9### 1. Say which version
📦 Turbo Core   11Create `release.env` — it is gitignored, so CI never sees it:
   12
14TAG="v0.1.0"
15ABOUT="The Turbo editor library"
📦 Turbo Core   18`ABOUT` becomes the tag's message, and the workflow reads it back off the tag to head the release page.
   20### 2. Run the script
23./01-release.tag.sh
26It 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.
28That 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.
📦 Turbo Core   30That is the last thing you run by hand. The library is published once the tag is on origin.
32### 3. Watch the Release workflow
34The tag push starts `.github/workflows/release.yml`. Follow it on the repository's Actions tab; nothing here needs you unless it goes red.
   35
📦 Turbo Core   36It runs the suite, stages the artefacts with `./02-build-releases.sh`, and creates the release page with them. The notes are the tag's message, the one line that installs the module, and links to the documentation **at that tag** rather than at the branch — a release page is not inside the repository tree, so a relative link from it 404s and a link to the branch rots as the branch moves.
38The 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.
40You can see what it will stage without publishing anything:
   41
📦 Turbo Core   43./02-build-releases.sh v0.1.0     # writes release/v0.1.0/, pushes nothing
   44
📦 Turbo Core   46It compiles every package, vets them, archives the source the tag is on, extracts that archive and builds it again — the one proof that what ships builds on its own, with nothing left untracked — then checksums it and writes the README that goes on the page.
   47
📦 Turbo Core   48That archive is not how anybody installs the library: the proxy serves the module straight from the tag. It is there to verify a release against, and for anyone who cannot reach the proxy.
   49
📦 Turbo Core   50There is no `03` or `04` here. Those build and attach binaries in the editors; a library has none.
   51
52### 4. Point the editors at it
54One editor at a time, running its suite before moving to the next:
📦 Turbo Core   57go mod edit -require=rickub.com/turbo-editors/turbo-core@v0.1.0
58go mod edit -dropreplace=rickub.com/turbo-editors/turbo-core
   59go mod tidy
60
63Every 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.
65## Variants
67### You would rather do it by hand
70
71git push origin main
72git tag -a v0.1.0 -m "The Turbo editor library"
73git push origin v0.1.0
📦 Turbo Core   76Push the branch **before** the tag, for the reason above. The workflow triggers on the tag push however it was made, so the release page still appears.
   77
78### You are developing across the three repositories
80Since 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:
83cd turbo-go
84go work init . ../turbo-core
87[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.
89### The change is not backwards compatible
91Say 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`.
93### You need to move a tag you have already pushed
95You do not. Several editors may pin it and the module proxy caches what it fetched, so the script refuses. Bump `TAG` instead.
97## What to watch out for
📦 Turbo Core   99The 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. The workflow sets the same variable for its own `go test` step, because there nothing calls the script that would have set it.
101The workflow is the repository's only one, on purpose: Rickub's dispatch API fires every dispatchable workflow of a ref, so a repository should declare at most one — which is also why this one has no `workflow_dispatch` and is reached only by pushing a tag.
   102
103## See also
105- Releasing an editor: each editor's `how-to/make-a-release.md`
106- What the tests cover: [Run the tests](run-the-tests.md)

🛟 Updated. 28d5985 k33g 19h 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
📦 Turbo Core d662ceb k33g 11h ago	5	turbo-core is a Go module with no binary: publishing it is tagging it, and the module proxy serves `go get …@TAG` the moment the tag is reachable. You run one script; pushing the tag starts a workflow that does the rest.
🛟 Updated. 28d5985 k33g 19h ago	6
	7	## Steps
	8
	9	### 1. Say which version
	10
📦 Turbo Core d662ceb k33g 11h ago	11	Create `release.env` — it is gitignored, so CI never sees it:
🛟 Updated. 28d5985 k33g 19h ago	12
	13	```sh
	14	TAG="v0.1.0"
	15	ABOUT="The Turbo editor library"
	16	```
	17
📦 Turbo Core d662ceb k33g 11h ago	18	`ABOUT` becomes the tag's message, and the workflow reads it back off the tag to head the release page.
📦 Turbo Core d662ceb k33g 11h ago	19
🛟 Updated. 28d5985 k33g 19h ago	20	### 2. Run the script
	21
	22	```bash
	23	./01-release.tag.sh
	24	```
	25
	26	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.
	27
	28	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.
	29
📦 Turbo Core d662ceb k33g 11h ago	30	That is the last thing you run by hand. The library is published once the tag is on origin.
	31
	32	### 3. Watch the Release workflow
	33
	34	The tag push starts `.github/workflows/release.yml`. Follow it on the repository's Actions tab; nothing here needs you unless it goes red.
🛟 Updated. 28d5985 k33g 19h ago	35
📦 Turbo Core d662ceb k33g 11h ago	36	It runs the suite, stages the artefacts with `./02-build-releases.sh`, and creates the release page with them. The notes are the tag's message, the one line that installs the module, and links to the documentation at that tag rather than at the branch — a release page is not inside the repository tree, so a relative link from it 404s and a link to the branch rots as the branch moves.
	37
	38	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.
	39
	40	You can see what it will stage without publishing anything:
🛟 Updated. 28d5985 k33g 19h ago	41
🛟 Updated. 28d5985 k33g 19h ago	42	```bash
📦 Turbo Core d662ceb k33g 11h ago	43	./02-build-releases.sh v0.1.0 # writes release/v0.1.0/, pushes nothing
🛟 Updated. 28d5985 k33g 19h ago	44	```
🛟 Updated. 28d5985 k33g 19h ago	45
📦 Turbo Core d662ceb k33g 11h ago	46	It compiles every package, vets them, archives the source the tag is on, extracts that archive and builds it again — the one proof that what ships builds on its own, with nothing left untracked — then checksums it and writes the README that goes on the page.
🛟 Updated. 28d5985 k33g 19h ago	47
📦 Turbo Core d662ceb k33g 11h ago	48	That archive is not how anybody installs the library: the proxy serves the module straight from the tag. It is there to verify a release against, and for anyone who cannot reach the proxy.
🛟 Updated. 28d5985 k33g 19h ago	49
📦 Turbo Core d662ceb k33g 11h ago	50	There is no `03` or `04` here. Those build and attach binaries in the editors; a library has none.
🛟 Updated. 28d5985 k33g 19h ago	51
	52	### 4. Point the editors at it
	53
	54	One editor at a time, running its suite before moving to the next:
	55
	56	```bash
📦 Turbo Core f3ade8d k33g 11h ago	57	go mod edit -require=rickub.com/turbo-editors/turbo-core@v0.1.0
📦 Turbo Core f3ade8d k33g 11h ago	58	go mod edit -dropreplace=rickub.com/turbo-editors/turbo-core
🛟 Updated. 28d5985 k33g 19h ago	59	go mod tidy
	60	make test
	61	```
	62
	63	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.
	64
	65	## Variants
	66
	67	### You would rather do it by hand
	68
	69	```bash
	70	make check
	71	git push origin main
	72	git tag -a v0.1.0 -m "The Turbo editor library"
	73	git push origin v0.1.0
	74	```
	75
📦 Turbo Core d662ceb k33g 11h ago	76	Push the branch before the tag, for the reason above. The workflow triggers on the tag push however it was made, so the release page still appears.
🛟 Updated. 28d5985 k33g 19h ago	77
	78	### You are developing across the three repositories
	79
	80	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:
	81
	82	```bash
	83	cd turbo-go
	84	go work init . ../turbo-core
	85	```
	86
	87	[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.
	88
	89	### The change is not backwards compatible
	90
	91	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`.
	92
	93	### You need to move a tag you have already pushed
	94
	95	You do not. Several editors may pin it and the module proxy caches what it fetched, so the script refuses. Bump `TAG` instead.
	96
	97	## What to watch out for
	98
📦 Turbo Core d662ceb k33g 11h ago	99	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. The workflow sets the same variable for its own `go test` step, because there nothing calls the script that would have set it.
	100
	101	The workflow is the repository's only one, on purpose: Rickub's dispatch API fires every dispatchable workflow of a ref, so a repository should declare at most one — which is also why this one has no `workflow_dispatch` and is reached only by pushing a tag.
🛟 Updated. 28d5985 k33g 19h ago	102
	103	## See also
	104
	105	- Releasing an editor: each editor's `how-to/make-a-release.md`
	106	- What the tests cover: [Run the tests](run-the-tests.md)