How to release the library

 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

# How to release the library

This 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 is a Go module with no binary and no release artefacts: publishing it is tagging it. `01-release.tag.sh` does the whole thing.

## Steps

### 1. Say which version

Create `release.env` — it is gitignored, because a release token belongs in one too:

```sh
TAG="v0.1.0"
ABOUT="The Turbo editor library"
```

### 2. Run the script

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

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.

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.

### 3. Create the release page

The tag is enough for `go get`; this adds the page a person reads.

```bash
./02-release.publish.sh --dry-run    # show the request, send nothing
./02-release.publish.sh              # create it
```

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

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.

There is no `03` or `04` here. Those build and attach binaries in the editors; a library has none — its artefact is the tag.

### 4. Point the editors at it

One editor at a time, running its suite before moving to the next:

```bash
go mod edit -require=codeberg.org/turbo-editors/turbo-core@v0.1.0
go mod edit -dropreplace=codeberg.org/turbo-editors/turbo-core
go mod tidy
make test
```

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.

## Variants

### You would rather do it by hand

```bash
make check
git push origin main
git tag -a v0.1.0 -m "The Turbo editor library"
git push origin v0.1.0
```

Push the branch **before** the tag, for the reason above.

### You are developing across the three repositories

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:

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

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

### The change is not backwards compatible

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

### You need to move a tag you have already pushed

You do not. Several editors may pin it and the module proxy caches what it fetched, so the script refuses. Bump `TAG` instead.

## What to watch out for

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.

## See also

- Releasing an editor: each editor's `how-to/make-a-release.md`
- What the tests cover: [Run the tests](run-the-tests.md)