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
 96
 97
 98
 99
100
101
102
103
104
105
106

# 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: 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.

## Steps

### 1. Say which version

Create `release.env` — it is gitignored, so CI never sees it:

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

`ABOUT` becomes the tag's message, and the workflow reads it back off the tag to head the release page.

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

That is the last thing you run by hand. The library is published once the tag is on origin.

### 3. Watch the Release workflow

The tag push starts `.github/workflows/release.yml`. Follow it on the repository's Actions tab; nothing here needs you unless it goes red.

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.

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.

You can see what it will stage without publishing anything:

```bash
./02-build-releases.sh v0.1.0     # writes release/v0.1.0/, pushes nothing
```

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.

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.

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

### 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. The workflow triggers on the tag push however it was made, so the release page still appears.

### 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. The workflow sets the same variable for its own `go test` step, because there nothing calls the script that would have set it.

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.

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