turbo-editors/turbo-core · test-without-publishing.md

⑂ v1.0.2

test-without-publishing.md · 106 lines · 4.8 KBmarkdown    Blame HistoryRaw
   1# How to test a change to turbo-core without publishing it
3This guide shows how to run Turbo Go or Turbo Rust against a turbo-core you have only changed locally, so you can see a library change working before you decide it is worth a version number. It assumes the three repositories are checked out side by side.
5## The problem
7The editors depend on turbo-core the way anyone else would — by module path and version:
📦 Turbo Core   10require rickub.com/turbo-editors/turbo-core v0.2.0
   11
13That version comes from the module proxy, not from the directory next door. A change you make in `../turbo-core` is invisible to the editors until it is tagged **and** published, which is exactly the wrong order: you would be publishing to find out whether the change works.
15## Use a workspace
17From the editor's directory:
20cd turbo-go
21go work init . ../turbo-core
24That is all. Build, test and run as usual:
27
28
29./bin/turbo-go
📦 Turbo Core   32Every import of `rickub.com/turbo-editors/turbo-core/...` now resolves to your checkout. Nothing in `go.mod` or `go.sum` changed, which is the whole point: there is no edit to undo and nothing to forget before committing.
   33
34### Check it took
📦 Turbo Core   37go list -f '{{.Dir}}' rickub.com/turbo-editors/turbo-core/app
   38
40| Answer | Meaning |
41| --- | --- |
42| `…/turbo-editors/turbo-core/app` | The workspace is in force; you are testing your changes |
📦 Turbo Core   43| `…/pkg/mod/rickub.com/…@v0.2.0/app` | It is not; you are testing the published library |
   44
45The second answer is the one that wastes an afternoon, because everything still builds and still passes.
47### Stop using it
50rm go.work go.work.sum
53`go.work` is gitignored in every one of these repositories, so it cannot be committed by accident. It is one person's local wiring: committed, it would break every clone that has no `../turbo-core` beside it.
55## Working on every editor at once
57A workspace can hold the library and all the editors built on it:
60cd turbo-editors
61go work init ./turbo-core ./turbo-go ./turbo-rust ./turbo-python ./turbo-moonbit ./turbo-golo ./turbo-js
64Put that `go.work` in the **parent** directory and every `go` command run under it — in any of the six — uses the local turbo-core. This is the shape to use when a library change touches more than one editor, which is most of them.
66**List every module the workspace covers, including nested ones.** A workspace claims the whole directory tree of each module it lists, so a second `go.mod` underneath one of them — a demo project, a scratch playground — stops being a module at all, and every `go` command run inside it fails with *directory prefix . does not contain modules listed in go.work*. Add it to the `use` block and it works again. A `use` entry pointing at a directory with **no** `go.mod` fails the whole workspace load instead, naming that directory rather than the one you were working in.
68## The older way: a replace directive
70Each editor's `go.mod` ends with the same line, commented out:
📦 Turbo Core   73// replace rickub.com/turbo-editors/turbo-core => ../turbo-core
   74
76Uncommenting it does the same job. It is kept because it is the form the Go documentation reaches for first and the one you will meet in older notes, but prefer the workspace, for one reason: **a `replace` is an edit to a tracked file, and can be committed by accident.** A committed `replace` breaks a clean clone on any machine without that checkout, and `01-release.tag.sh` refuses to tag a release with one in `go.mod` — which is the safety net telling you the mistake is common enough to be worth a check.
78If you do use it, put the `require` line back to a published version and delete the `replace` before you commit.
80## Testing the published shape, not just the code
📦 Turbo Core   82A workspace proves your code works. It does not prove the *module* works: it says nothing about whether the tag contains what you think, whether `go.sum` is right, or whether a clean clone builds.
84The last of those you can answer without publishing anything — `./02-build-releases.sh v0.3.0` archives the tracked source, extracts it somewhere else and builds it there. The rest needs a real tag:
   85
📦 Turbo Core   87./01-release.tag.sh
   88
📦 Turbo Core   90The release page follows on its own: pushing the tag starts the Release workflow, which stages the same artefacts and publishes them. See [Release the library](release-the-library.md).
   92Then, in each editor, with **no** workspace and **no** replace:
95rm -f go.work go.work.sum
📦 Turbo Core   96go get rickub.com/turbo-editors/turbo-core@v0.3.0
   97go mod tidy
98
101A published tag cannot be moved — consumers pin it and the proxy caches it — so do this after the workspace has convinced you, never instead of it.
103## See also
105- Cutting the release itself: [How to release the library](release-the-library.md)
106- Running the suite: [How to run the tests](run-the-tests.md)

🛟 Updated. 28d5985 k33g 21h ago	1	# How to test a change to turbo-core without publishing it
	2
	3	This guide shows how to run Turbo Go or Turbo Rust against a turbo-core you have only changed locally, so you can see a library change working before you decide it is worth a version number. It assumes the three repositories are checked out side by side.
	4
	5	## The problem
	6
	7	The editors depend on turbo-core the way anyone else would — by module path and version:
	8
	9	```
📦 Turbo Core f3ade8d k33g 13h ago	10	require rickub.com/turbo-editors/turbo-core v0.2.0
🛟 Updated. 28d5985 k33g 21h ago	11	```
	12
	13	That version comes from the module proxy, not from the directory next door. A change you make in `../turbo-core` is invisible to the editors until it is tagged and published, which is exactly the wrong order: you would be publishing to find out whether the change works.
	14
	15	## Use a workspace
	16
	17	From the editor's directory:
	18
	19	```bash
	20	cd turbo-go
	21	go work init . ../turbo-core
	22	```
	23
	24	That is all. Build, test and run as usual:
	25
	26	```bash
	27	make test
	28	make build
	29	./bin/turbo-go
	30	```
	31
📦 Turbo Core f3ade8d k33g 13h ago	32	Every import of `rickub.com/turbo-editors/turbo-core/...` now resolves to your checkout. Nothing in `go.mod` or `go.sum` changed, which is the whole point: there is no edit to undo and nothing to forget before committing.
🛟 Updated. 28d5985 k33g 21h ago	33
	34	### Check it took
	35
	36	```bash
📦 Turbo Core f3ade8d k33g 13h ago	37	go list -f '{{.Dir}}' rickub.com/turbo-editors/turbo-core/app
🛟 Updated. 28d5985 k33g 21h ago	38	```
	39
	40	\| Answer \| Meaning \|
	41	\| --- \| --- \|
	42	\| `…/turbo-editors/turbo-core/app` \| The workspace is in force; you are testing your changes \|
📦 Turbo Core f3ade8d k33g 13h ago	43	\| `…/pkg/mod/rickub.com/…@v0.2.0/app` \| It is not; you are testing the published library \|
🛟 Updated. 28d5985 k33g 21h ago	44
	45	The second answer is the one that wastes an afternoon, because everything still builds and still passes.
	46
	47	### Stop using it
	48
	49	```bash
	50	rm go.work go.work.sum
	51	```
	52
	53	`go.work` is gitignored in every one of these repositories, so it cannot be committed by accident. It is one person's local wiring: committed, it would break every clone that has no `../turbo-core` beside it.
	54
	55	## Working on every editor at once
	56
	57	A workspace can hold the library and all the editors built on it:
	58
	59	```bash
	60	cd turbo-editors
	61	go work init ./turbo-core ./turbo-go ./turbo-rust ./turbo-python ./turbo-moonbit ./turbo-golo ./turbo-js
	62	```
	63
	64	Put that `go.work` in the parent directory and every `go` command run under it — in any of the six — uses the local turbo-core. This is the shape to use when a library change touches more than one editor, which is most of them.
	65
	66	List every module the workspace covers, including nested ones. A workspace claims the whole directory tree of each module it lists, so a second `go.mod` underneath one of them — a demo project, a scratch playground — stops being a module at all, and every `go` command run inside it fails with directory prefix . does not contain modules listed in go.work. Add it to the `use` block and it works again. A `use` entry pointing at a directory with no `go.mod` fails the whole workspace load instead, naming that directory rather than the one you were working in.
	67
	68	## The older way: a replace directive
	69
	70	Each editor's `go.mod` ends with the same line, commented out:
	71
	72	```
📦 Turbo Core f3ade8d k33g 13h ago	73	// replace rickub.com/turbo-editors/turbo-core => ../turbo-core
🛟 Updated. 28d5985 k33g 21h ago	74	```
	75
	76	Uncommenting it does the same job. It is kept because it is the form the Go documentation reaches for first and the one you will meet in older notes, but prefer the workspace, for one reason: a `replace` is an edit to a tracked file, and can be committed by accident. A committed `replace` breaks a clean clone on any machine without that checkout, and `01-release.tag.sh` refuses to tag a release with one in `go.mod` — which is the safety net telling you the mistake is common enough to be worth a check.
	77
	78	If you do use it, put the `require` line back to a published version and delete the `replace` before you commit.
	79
	80	## Testing the published shape, not just the code
	81
📦 Turbo Core d662ceb k33g 13h ago	82	A workspace proves your code works. It does not prove the module works: it says nothing about whether the tag contains what you think, whether `go.sum` is right, or whether a clean clone builds.
	83
	84	The last of those you can answer without publishing anything — `./02-build-releases.sh v0.3.0` archives the tracked source, extracts it somewhere else and builds it there. The rest needs a real tag:
🛟 Updated. 28d5985 k33g 21h ago	85
🛟 Updated. 28d5985 k33g 21h ago	86	```bash
📦 Turbo Core d662ceb k33g 13h ago	87	./01-release.tag.sh
🛟 Updated. 28d5985 k33g 21h ago	88	```
🛟 Updated. 28d5985 k33g 21h ago	89
📦 Turbo Core d662ceb k33g 13h ago	90	The release page follows on its own: pushing the tag starts the Release workflow, which stages the same artefacts and publishes them. See [Release the library](release-the-library.md).
📦 Turbo Core d662ceb k33g 13h ago	91
🛟 Updated. 28d5985 k33g 21h ago	92	Then, in each editor, with no workspace and no replace:
	93
	94	```bash
	95	rm -f go.work go.work.sum
📦 Turbo Core f3ade8d k33g 13h ago	96	go get rickub.com/turbo-editors/turbo-core@v0.3.0
🛟 Updated. 28d5985 k33g 21h ago	97	go mod tidy
	98	make check
	99	```
	100
	101	A published tag cannot be moved — consumers pin it and the proxy caches it — so do this after the workspace has convinced you, never instead of it.
	102
	103	## See also
	104
	105	- Cutting the release itself: [How to release the library](release-the-library.md)
	106	- Running the suite: [How to run the tests](run-the-tests.md)