Skip to content

Commit bfb87fa

Browse files
committed
Add release tooling
Signed-off-by: Mangirdas Judeikis <mangirdas@judeikis.lt>
1 parent f7726f0 commit bfb87fa

2 files changed

Lines changed: 327 additions & 0 deletions

File tree

‎cmd/release/main.go‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
/*
2+
Copyright 2026 The Kube Bind Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
// Command release computes and creates the next v2 release-candidate tag.
18+
//
19+
// It inspects the tags already present on an upstream remote, finds the highest
20+
// release candidate for the target version (default v2.0.0), and creates the
21+
// next one (e.g. v2.0.0-rc3 if rc2 is the highest upstream). Pushing the tag to
22+
// the remote triggers the Image workflow, so pushing is gated behind -push.
23+
//
24+
// Usage:
25+
//
26+
// go run ./cmd/release # compute + create the next rc tag locally
27+
// go run ./cmd/release -dry-run # only print what would be created
28+
// go run ./cmd/release -push # create and push the tag to the remote
29+
package main
30+
31+
import (
32+
"flag"
33+
"fmt"
34+
"os"
35+
"os/exec"
36+
"regexp"
37+
"sort"
38+
"strconv"
39+
"strings"
40+
)
41+
42+
// options holds the release tool's flags.
43+
type options struct {
44+
remote string
45+
version string
46+
push bool
47+
dryRun bool
48+
}
49+
50+
func newFlagSet(o *options) *flag.FlagSet {
51+
fs := flag.NewFlagSet("release", flag.ContinueOnError)
52+
fs.StringVar(&o.remote, "remote", "origin", "git remote to read existing tags from and push to")
53+
fs.StringVar(&o.version, "version", "v2.0.0", "target GA version the release candidates lead up to")
54+
fs.BoolVar(&o.push, "push", false, "push the created tag to the remote (triggers the Image workflow)")
55+
fs.BoolVar(&o.dryRun, "dry-run", false, "only print the tag that would be created")
56+
return fs
57+
}
58+
59+
func main() {
60+
if err := run(); err != nil {
61+
fmt.Fprintln(os.Stderr, "error:", err)
62+
os.Exit(1)
63+
}
64+
}
65+
66+
func run() error {
67+
var o options
68+
fs := newFlagSet(&o)
69+
if err := fs.Parse(os.Args[1:]); err != nil {
70+
return err
71+
}
72+
73+
if !strings.HasPrefix(o.version, "v2.") {
74+
return fmt.Errorf("target version %q is not a v2 version", o.version)
75+
}
76+
77+
tags, err := remoteTags(o.remote)
78+
if err != nil {
79+
return err
80+
}
81+
82+
next := nextRC(o.version, tags)
83+
fmt.Printf("remote %q: highest rc for %s -> next tag %s\n", o.remote, o.version, next)
84+
85+
if o.dryRun {
86+
return nil
87+
}
88+
89+
if localTagExists(next) {
90+
return fmt.Errorf("tag %s already exists locally; delete it first or bump the version", next)
91+
}
92+
93+
if err := gitRun("tag", "-a", next, "-m", next); err != nil {
94+
return fmt.Errorf("creating tag %s: %w", next, err)
95+
}
96+
fmt.Printf("created annotated tag %s on HEAD\n", next)
97+
98+
if !o.push {
99+
fmt.Printf("not pushed. To publish (triggers the Image workflow):\n\n git push %s %s\n", o.remote, next)
100+
return nil
101+
}
102+
103+
if err := gitRun("push", o.remote, next); err != nil {
104+
return fmt.Errorf("pushing tag %s to %s: %w", next, o.remote, err)
105+
}
106+
fmt.Printf("pushed %s to %s — the Image workflow will build ghcr.io/<owner>/konnector:%s\n", next, o.remote, next)
107+
return nil
108+
}
109+
110+
// rcTagRE matches a release-candidate tag and captures the rc number, e.g.
111+
// "v2.0.0-rc3" -> "3".
112+
var rcTagRE = regexp.MustCompile(`^(v\d+\.\d+\.\d+)-rc(\d+)$`)
113+
114+
// nextRC returns the next release-candidate tag for version, given the set of
115+
// existing tags. If no rc exists for version yet it returns "<version>-rc1".
116+
func nextRC(version string, tags []string) string {
117+
highest := 0
118+
for _, t := range tags {
119+
m := rcTagRE.FindStringSubmatch(t)
120+
if m == nil || m[1] != version {
121+
continue
122+
}
123+
n, err := strconv.Atoi(m[2])
124+
if err != nil {
125+
continue
126+
}
127+
if n > highest {
128+
highest = n
129+
}
130+
}
131+
return fmt.Sprintf("%s-rc%d", version, highest+1)
132+
}
133+
134+
// remoteTags lists the tag names present on the given remote via
135+
// `git ls-remote --tags`, so no local fetch is required. Dereferenced tag refs
136+
// (the "^{}" suffix) are collapsed to their base tag name.
137+
func remoteTags(remote string) ([]string, error) {
138+
out, err := gitOutput("ls-remote", "--tags", remote)
139+
if err != nil {
140+
return nil, fmt.Errorf("listing tags on remote %q: %w", remote, err)
141+
}
142+
seen := map[string]struct{}{}
143+
var tags []string
144+
for line := range strings.SplitSeq(strings.TrimSpace(out), "\n") {
145+
fields := strings.Fields(line)
146+
if len(fields) != 2 {
147+
continue
148+
}
149+
ref := strings.TrimPrefix(fields[1], "refs/tags/")
150+
ref = strings.TrimSuffix(ref, "^{}")
151+
if _, ok := seen[ref]; ok {
152+
continue
153+
}
154+
seen[ref] = struct{}{}
155+
tags = append(tags, ref)
156+
}
157+
sort.Strings(tags)
158+
return tags, nil
159+
}
160+
161+
// localTagExists reports whether tag already exists in the local repository.
162+
func localTagExists(tag string) bool {
163+
return gitRun("rev-parse", "--verify", "--quiet", "refs/tags/"+tag) == nil
164+
}
165+
166+
func gitRun(args ...string) error {
167+
cmd := exec.Command("git", args...)
168+
cmd.Stdout = os.Stdout
169+
cmd.Stderr = os.Stderr
170+
return cmd.Run()
171+
}
172+
173+
func gitOutput(args ...string) (string, error) {
174+
cmd := exec.Command("git", args...)
175+
cmd.Stderr = os.Stderr
176+
out, err := cmd.Output()
177+
return string(out), err
178+
}

‎docs/RELEASING.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Releasing
2+
3+
This document describes how to cut a v2 release and how to create release
4+
branches for future maintenance.
5+
6+
## How releases work
7+
8+
Releases are driven entirely by git tags. Pushing a tag that matches `v*`
9+
triggers the [Image workflow](../.github/workflows/image.yaml), which builds the
10+
multi-arch `konnector` image and pushes it to the GitHub Container Registry:
11+
12+
```
13+
ghcr.io/<owner>/konnector:<tag>
14+
```
15+
16+
There is no `:latest` or `:<sha>` tag — the image registry is shared with the
17+
v1/`main` images, so only the exact version tag is published.
18+
19+
Version tags follow [semantic versioning](https://semver.org):
20+
21+
- `v2.0.0-rc1`, `v2.0.0-rc2`, … — release candidates (pre-releases).
22+
- `v2.0.0` — the final GA release.
23+
- `v2.0.1`, `v2.1.0`, … — patch / minor releases.
24+
25+
## Cutting a release candidate
26+
27+
Release candidates are cut directly from `v2-next` (the v2 development branch)
28+
until GA, then from the release branch (see below).
29+
30+
### The `release` helper
31+
32+
Rather than working out the next rc number by hand, use the
33+
[`cmd/release`](../cmd/release) tool. It reads the tags already on the upstream
34+
remote, finds the highest rc for the target version, and creates the next one:
35+
36+
```bash
37+
# see what the next tag would be, without creating anything
38+
go run ./cmd/release -dry-run
39+
40+
# create the next rc tag locally (e.g. v2.0.0-rc3)
41+
go run ./cmd/release
42+
43+
# create AND push it (this triggers the Image workflow)
44+
go run ./cmd/release -push
45+
```
46+
47+
Flags: `-remote` (default `origin`), `-version` (default `v2.0.0`, the GA
48+
version the candidates lead up to), `-push`, and `-dry-run`. The tag is created
49+
on your current `HEAD`, so check out the commit you intend to release first.
50+
51+
### Cutting one by hand
52+
53+
1. Make sure your local checkout is up to date and on the branch you are
54+
releasing from:
55+
56+
```bash
57+
git checkout v2-next
58+
git pull --ff-only
59+
```
60+
61+
2. Confirm CI is green for the commit you are about to tag.
62+
63+
3. Create an annotated tag and push it:
64+
65+
```bash
66+
git tag -a v2.0.0-rc1 -m "v2.0.0-rc1"
67+
git push origin v2.0.0-rc1
68+
```
69+
70+
4. The Image workflow runs automatically. When it finishes, the image is
71+
available at `ghcr.io/<owner>/konnector:v2.0.0-rc1`.
72+
73+
5. (Optional) Create a GitHub Release from the tag and mark it as a
74+
pre-release:
75+
76+
```bash
77+
gh release create v2.0.0-rc1 --prerelease --generate-notes
78+
```
79+
80+
Repeat with `-rc2`, `-rc3`, … as needed until the candidate is stable.
81+
82+
## Cutting the GA release
83+
84+
Once a release candidate is deemed stable, tag the same commit (or the tip of
85+
the release branch) as the final version:
86+
87+
```bash
88+
git tag -a v2.0.0 -m "v2.0.0"
89+
git push origin v2.0.0
90+
gh release create v2.0.0 --generate-notes
91+
```
92+
93+
## Creating a release branch
94+
95+
Once `v2.0.0` ships, create a long-lived `release-2.0` branch so that
96+
`v2-next`/`main` can move on to the next minor version while patch releases can
97+
still be cut from the stable line.
98+
99+
1. Branch from the GA tag (or the commit you released):
100+
101+
```bash
102+
git checkout -b release-2.0 v2.0.0
103+
git push origin release-2.0
104+
```
105+
106+
2. Wire the branch into CI so pushes and PRs against it run the test suite. In
107+
[.github/workflows/ci.yaml](../.github/workflows/ci.yaml), add the branch to
108+
both the `push` and `pull_request` branch lists:
109+
110+
```yaml
111+
on:
112+
push:
113+
branches:
114+
- main
115+
- v2-next
116+
- release-2.0
117+
pull_request:
118+
branches:
119+
- main
120+
- v2-next
121+
- release-2.0
122+
```
123+
124+
(The Image workflow triggers on `v*` tags regardless of branch, so it needs
125+
no change.)
126+
127+
### Patch releases from a release branch
128+
129+
Cherry-pick or merge fixes into `release-2.0`, then tag the patch version from
130+
that branch:
131+
132+
```bash
133+
git checkout release-2.0
134+
git pull --ff-only
135+
# ... land fixes here ...
136+
git tag -a v2.0.1 -m "v2.0.1"
137+
git push origin v2.0.1
138+
gh release create v2.0.1 --generate-notes
139+
```
140+
141+
## Naming conventions
142+
143+
| Kind | Example | Cut from |
144+
|------------------|----------------|-----------------|
145+
| Release candidate| `v2.0.0-rc1` | `v2-next` |
146+
| GA release | `v2.0.0` | `v2-next` |
147+
| Release branch | `release-2.0` | tag `v2.0.0` |
148+
| Patch release | `v2.0.1` | `release-2.0` |
149+
| Next minor branch| `release-2.1` | tag `v2.1.0` |

0 commit comments

Comments
 (0)