How to test a change to turbo-core without publishing it

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106

# How to test a change to turbo-core without publishing it

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.

## The problem

The editors depend on turbo-core the way anyone else would — by module path and version:

```
require rickub.com/turbo-editors/turbo-core v0.2.0
```

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.

## Use a workspace

From the editor's directory:

```bash
cd turbo-go
go work init . ../turbo-core
```

That is all. Build, test and run as usual:

```bash
make test
make build
./bin/turbo-go
```

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.

### Check it took

```bash
go list -f '{{.Dir}}' rickub.com/turbo-editors/turbo-core/app
```

| Answer | Meaning |
| --- | --- |
| `…/turbo-editors/turbo-core/app` | The workspace is in force; you are testing your changes |
| `…/pkg/mod/rickub.com/…@v0.2.0/app` | It is not; you are testing the published library |

The second answer is the one that wastes an afternoon, because everything still builds and still passes.

### Stop using it

```bash
rm go.work go.work.sum
```

`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.

## Working on every editor at once

A workspace can hold the library and all the editors built on it:

```bash
cd turbo-editors
go work init ./turbo-core ./turbo-go ./turbo-rust ./turbo-python ./turbo-moonbit ./turbo-golo ./turbo-js
```

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.

**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.

## The older way: a replace directive

Each editor's `go.mod` ends with the same line, commented out:

```
// replace rickub.com/turbo-editors/turbo-core => ../turbo-core
```

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.

If you do use it, put the `require` line back to a published version and delete the `replace` before you commit.

## Testing the published shape, not just the code

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.

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:

```bash
./01-release.tag.sh
```

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).

Then, in each editor, with **no** workspace and **no** replace:

```bash
rm -f go.work go.work.sum
go get rickub.com/turbo-editors/turbo-core@v0.3.0
go mod tidy
make check
```

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.

## See also

- Cutting the release itself: [How to release the library](release-the-library.md)
- Running the suite: [How to run the tests](run-the-tests.md)