Skip to content

Commit e6f943b

Browse files
urvisavlaurvisavla
authored
Add RELEASE.md documenting release flows (#74)
Documents the two release flows for Galexie: - Major release (with optional RC) from a release/vX.Y.Z branch cut off protocol-next, merged back to main. - Minor or patch release (including stellar-core refresh) shipped directly from main. Also describes the underlying CI wiring (publish-sha-tag-image and publish-release-tag-image) and uses GitHub Releases as the tag-creation mechanism so no manual git tag pushes are needed.
1 parent f5e4899 commit e6f943b

1 file changed

Lines changed: 132 additions & 0 deletions

File tree

‎RELEASE.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Releasing Galexie
2+
3+
Galexie uses [Semantic Versioning](https://semver.org/) and is released as:
4+
- A git tag of the form `galexie-vX.Y.Z` (e.g. `galexie-v26.0.0`, `galexie-v26.0.0-rc1`).
5+
- A Docker image published to `stellar/stellar-galexie:X.Y.Z` on Docker Hub.
6+
When the tag does not contain `-rc`, the image is also tagged `latest`.
7+
8+
1. [Major release (with optional RC)](#1-major-release-with-optional-rc) — new protocol
9+
versions or any release that wants an RC cycle / isolation from ongoing `main` work.
10+
2. [Minor or patch release (including `stellar-core` refresh)](#2-minor-or-patch-release-including-stellar-core-refresh)
11+
— bug fixes, small features, or refreshing the `stellar-core` bundled in the Docker image,
12+
shipped directly from `main`.
13+
14+
---
15+
16+
## How releases are wired up
17+
18+
Two jobs in `.github/workflows/galexie.yml` do the publishing:
19+
20+
- `publish-sha-tag-image` — runs on every push to `main` or `release/**`. Builds and pushes
21+
`stellar/stellar-galexie:<short-sha>`.
22+
- `publish-release-tag-image` — runs on any `galexie-v*` tag push. Pulls the sha-tagged image
23+
from that commit, re-tags it as `stellar/stellar-galexie:X.Y.Z`, and pushes `:latest` for
24+
non-rc tags. **`publish-sha-tag-image` must have succeeded on the target commit first**,
25+
since this job pulls rather than rebuilds.
26+
27+
---
28+
29+
## 1. Major release (with optional RC)
30+
31+
Use this flow when shipping a new major protocol version (e.g. `v26.0.0` for Protocol 26) or
32+
any release where you want an RC cycle and/or to isolate the release from ongoing work on
33+
`main`, using a dedicated `release/vX.Y.Z` branch.
34+
35+
Protocol work is developed on the long-running `protocol-next` branch in parallel with `main`.
36+
`main` is periodically merged **into** `protocol-next` to keep it up to date (see e.g. PR #67).
37+
When the protocol is ready to ship, `release/vX.Y.Z` is cut **from `protocol-next`** — not from
38+
`main`. Once the release is published, the release branch is merged back into `main`, which is
39+
how the protocol work ultimately lands on `main`.
40+
41+
### Steps
42+
43+
1. **Create the release branch** off `protocol-next` once the work to be shipped is ready:
44+
```
45+
git checkout protocol-next
46+
git pull
47+
git checkout -b release/vX.Y.Z
48+
git push -u origin release/vX.Y.Z
49+
```
50+
51+
2. **Verify the `stellar-core` pins** in `.github/workflows/galexie.yml` are set to the
52+
intended versions: `STELLAR_CORE_VERSION` (baked into the shipped image) and
53+
`CAPTIVE_CORE_DEBIAN_PKG_VERSION` (the integration-test core binary, which should match
54+
`STELLAR_CORE_VERSION` so tests run against the same binary that ships).
55+
56+
3. **Update `CHANGELOG.md`** with a new `## [vX.Y.Z]` section describing the changes since the
57+
last release. Follow the style of previous entries (Updates / New Features / Bug Fixes /
58+
Breaking Changes) and include PR links. Open as a PR against `release/vX.Y.Z`.
59+
60+
4. **Confirm the sha-tag image exists.** Verify that `publish-sha-tag-image` on the tip of
61+
`release/vX.Y.Z` has succeeded and that `stellar/stellar-galexie:<short-sha>` is on Docker
62+
Hub for that commit.
63+
64+
5. **Publish the GitHub Release.** If the bundled `stellar-core` is itself at RC, first run
65+
through this step with `galexie-vX.Y.Z-rc1` as the tag and **Set as a pre-release** checked
66+
instead of **Set as the latest release**. The `latest` Docker tag is not moved for `-rc`
67+
tags. Validate the RC end-to-end, then repeat this step for the final release.
68+
69+
On <https://github.com/stellar/stellar-galexie/releases/new>:
70+
- **Choose a tag:** type `galexie-vX.Y.Z` and pick "Create new tag on publish".
71+
- **Target:** `release/vX.Y.Z`.
72+
- **Set as the latest release:** checked.
73+
- Paste the changelog section as the notes.
74+
75+
Publishing creates the tag and triggers `publish-release-tag-image`. Wait for it to finish
76+
and confirm `stellar/stellar-galexie:X.Y.Z` and `stellar/stellar-galexie:latest` are on
77+
Docker Hub.
78+
79+
6. **Merge the release branch back to `main`.** Open a PR from `release/vX.Y.Z` to `main`.
80+
81+
---
82+
83+
## 2. Minor or patch release (including `stellar-core` refresh)
84+
85+
Use this flow for minor or patch releases shipped directly from `main` (e.g. `v25.1.1`) —
86+
bug fixes, small features, or **refreshing the `stellar-core` bundled in the Docker image**
87+
(e.g. picking up a new patch/minor of core with fixes).
88+
89+
For a pure core refresh, the source change is to update `STELLAR_CORE_VERSION` in
90+
`.github/workflows/galexie.yml` (the version baked into the shipped image), plus
91+
`CAPTIVE_CORE_DEBIAN_PKG_VERSION` to match. Always cut a new patch version so consumers pinned
92+
to the previous patch keep getting the old image.
93+
94+
### Steps
95+
96+
1. **Confirm `main` is in a releasable state** — CI is green and any version-pinning changes
97+
you want to ship are already merged.
98+
99+
2. **Update `CHANGELOG.md`** on `main` with the new `## [vX.Y.Z]` section. Submit as a PR and
100+
merge before publishing the release. For a pure core refresh a single-line entry is fine:
101+
```
102+
## [vX.Y.Z]
103+
104+
### Updates
105+
- Bumped bundled stellar-core to <new-core-version>.
106+
```
107+
108+
3. **Wait for the `publish-sha-tag-image` workflow** on the merge commit to succeed.
109+
110+
4. **Publish a GitHub Release.** On
111+
<https://github.com/stellar/stellar-galexie/releases/new>:
112+
- **Choose a tag:** type `galexie-vX.Y.Z` and pick "Create new tag on publish".
113+
- **Target:** `main` (at the merge commit from step 2).
114+
- **Set as the latest release:** checked.
115+
- Paste the changelog section as the notes.
116+
117+
5. **Verify** `publish-release-tag-image` succeeds and the new `stellar/stellar-galexie:X.Y.Z`
118+
(and `latest`) image is on Docker Hub. For a core refresh, also confirm the image contains
119+
the intended `stellar-core` version.
120+
121+
---
122+
123+
## Quick checklist
124+
125+
- [ ] `STELLAR_CORE_VERSION` and `CAPTIVE_CORE_DEBIAN_PKG_VERSION` in
126+
`.github/workflows/galexie.yml` point at the intended core version and match each other.
127+
- [ ] `CHANGELOG.md` has an entry for the new version.
128+
- [ ] `publish-sha-tag-image` workflow has succeeded on the commit being released.
129+
- [ ] Tag is of the form `galexie-vX.Y.Z` (or `galexie-vX.Y.Z-rcN` for release candidates).
130+
- [ ] `publish-release-tag-image` workflow succeeded after the GitHub Release was published.
131+
- [ ] Docker Hub shows the new `X.Y.Z` tag (and `latest`, for non-rc releases).
132+
- [ ] For major releases: release branch merged back to `main`.

0 commit comments

Comments
 (0)