Skip to content

Commit f044099

Browse files
ffarallffarall
authored
feat: 🚀 Add release process docs and CI (#541)
* docs: 📝 Add release process docs and template * ci: 👷 Add release CI * docs: 📝 Minor fixes in docs
1 parent c81ce2f commit f044099

File tree

3 files changed

+293
-0
lines changed

3 files changed

+293
-0
lines changed

‎.github/workflows/release-publish.yml‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
name: Publish on Release
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
jobs:
8+
docker-backend:
9+
name: Build & Push Backend Docker Image
10+
runs-on: blacksmith-16vcpu-ubuntu-2404
11+
steps:
12+
- uses: actions/checkout@v4
13+
14+
- name: Prepare Docker tags
15+
id: prep
16+
run: |
17+
DOCKER_IMAGE=moonsonglabs/storage-hub-msp-backend
18+
TAG=${GITHUB_REF_NAME}
19+
MINOR_TAG=v${TAG#v}
20+
MINOR_TAG=${MINOR_TAG%.*}
21+
TAGS="${DOCKER_IMAGE}:${TAG}\n${DOCKER_IMAGE}:${MINOR_TAG}"
22+
echo "tags=${TAGS}" >> $GITHUB_OUTPUT
23+
echo "created=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> $GITHUB_OUTPUT
24+
25+
- name: Set up QEMU
26+
uses: docker/setup-qemu-action@v3
27+
28+
- name: Set up Blacksmith Builder
29+
uses: useblacksmith/setup-docker-builder@v1
30+
31+
- name: Login to Docker Hub
32+
uses: docker/login-action@v3
33+
with:
34+
username: ${{ secrets.DOCKER_USERNAME }}
35+
password: ${{ secrets.DOCKER_TOKEN }}
36+
37+
- name: Build Docker image and push it to Docker Hub
38+
uses: useblacksmith/build-push-action@v2
39+
with:
40+
context: .
41+
file: ./docker/storage-hub-msp-backend.Dockerfile
42+
push: true
43+
platforms: linux/amd64
44+
tags: ${{ steps.prep.outputs.tags }}
45+
labels: |
46+
org.opencontainers.image.title=${{ github.event.repository.name }}-msp-backend
47+
org.opencontainers.image.description=Storage Hub MSP Backend
48+
org.opencontainers.image.url=${{ github.event.repository.html_url }}
49+
org.opencontainers.image.source=${{ github.event.repository.clone_url }}
50+
org.opencontainers.image.revision=${{ github.sha }}
51+
org.opencontainers.image.created=${{ steps.prep.outputs.created }}
52+
org.opencontainers.image.licenses=${{ github.event.repository.license.spdx_id }}
53+
54+
npm-packages:
55+
name: Publish npm packages (sdk, api-augment, types-bundle)
56+
runs-on: blacksmith-16vcpu-ubuntu-2404
57+
env:
58+
NODE_AUTH_TOKEN: ${{ secrets.SH_SDK_PUBLISH_TOKEN }}
59+
steps:
60+
- name: Checkout repository
61+
uses: actions/checkout@v4
62+
63+
- name: Setup pnpm & cache
64+
uses: ./.github/workflow-templates/setup-pnpm
65+
66+
- name: Setup Rust toolchain (for wasm)
67+
uses: actions-rust-lang/[email protected]
68+
with:
69+
target: wasm32-unknown-unknown
70+
cache: false
71+
72+
- name: Cache wasm-pack
73+
uses: actions/cache@v3
74+
with:
75+
path: ~/.cargo/bin/wasm-pack
76+
key: wasm-pack-v0.12.1
77+
78+
- name: Install wasm-pack
79+
run: curl -sSf https://rustwasm.github.io/wasm-pack/installer/init.sh | sh
80+
81+
- name: Extract version from tag
82+
id: vars
83+
run: |
84+
TAG=${GITHUB_REF_NAME}
85+
VERSION=${TAG#v}
86+
echo "version=${VERSION}" >> $GITHUB_OUTPUT
87+
88+
- name: Build core
89+
working-directory: sdk/core
90+
run: |
91+
pnpm install --frozen-lockfile
92+
pnpm run build
93+
94+
- name: Build msp-client
95+
working-directory: sdk/msp-client
96+
run: |
97+
pnpm install --frozen-lockfile
98+
pnpm run build
99+
100+
- name: Set SDK versions (no commit)
101+
working-directory: sdk
102+
run: |
103+
jq --arg v "${{ steps.vars.outputs.version }}" '.version=$v' core/package.json > core/package.json.tmp && mv core/package.json.tmp core/package.json
104+
jq --arg v "${{ steps.vars.outputs.version }}" '.version=$v' msp-client/package.json > msp-client/package.json.tmp && mv msp-client/package.json.tmp msp-client/package.json
105+
106+
- name: Pack and publish core
107+
working-directory: sdk/core
108+
run: |
109+
pnpm pack
110+
pnpm publish --access public --no-git-checks
111+
112+
- name: Pack and publish msp-client
113+
working-directory: sdk/msp-client
114+
run: |
115+
pnpm pack
116+
pnpm publish --access public --no-git-checks
117+
118+
- name: Prepare and publish types-bundle
119+
working-directory: types-bundle
120+
run: |
121+
jq --arg v "${{ steps.vars.outputs.version }}" '.version=$v' package.json > package.json.tmp && mv package.json.tmp package.json
122+
pnpm install --frozen-lockfile || true
123+
pnpm run build || true
124+
pnpm publish --access public --no-git-checks
125+
126+
- name: Prepare and publish api-augment
127+
working-directory: api-augment
128+
run: |
129+
jq --arg v "${{ steps.vars.outputs.version }}" '.version=$v' package.json > package.json.tmp && mv package.json.tmp package.json
130+
pnpm install --frozen-lockfile || true
131+
pnpm run build || true
132+
pnpm publish --access public --no-git-checks

‎RELEASE_NOTES_TEMPLATE.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# StorageHub vX.Y.Z
2+
3+
## Summary
4+
5+
Short paragraph summarising the release.
6+
7+
## Components
8+
9+
- Client code: vX.Y.Z
10+
- Pallets code: vX.Y.Z
11+
- Runtime code: vX.Y.Z (spec_name/spec_version: ...)
12+
- SH Backend Docker image: vX.Y.Z (image: ghcr.io/<org>/storage-hub-msp-backend:vX.Y.Z)
13+
- SH SDK (npm): vX.Y.Z
14+
- types-bundle/api-augment (npm): vX.Y.Z
15+
16+
## Changes since last tag
17+
18+
Base: <commit or tag>
19+
20+
- Highlights:
21+
- ...
22+
- Full diff: <compare link>
23+
- PRs included:
24+
- #NNN Title
25+
- ...
26+
27+
## Migrations
28+
29+
### RocksDB (File Storage)
30+
31+
- Changes:
32+
- Action required:
33+
34+
### RocksDB (Forest Storage)
35+
36+
- Changes:
37+
- Action required:
38+
39+
### RocksDB (State store)
40+
41+
- Changes:
42+
- Action required:
43+
44+
### Indexer DB (Postgres)
45+
46+
- Migrations:
47+
- <timestamp>\_<name>
48+
- How to apply: The indexer service runs migrations on startup. Alternatively: `diesel migration run`.
49+
50+
## Runtime
51+
52+
- Upgrades (spec_version): ...
53+
- Migrations: ...
54+
- Constants changed: ...
55+
- Scripts to run: ...
56+
57+
## Client
58+
59+
- Behaviour changes: ...
60+
- Initialisation changes: ...
61+
62+
## Backend
63+
64+
- Behaviour changes: ...
65+
- Initialisation changes: ...
66+
67+
## SDK
68+
69+
- Behaviour changes: ...
70+
- Initialisation changes: ...
71+
72+
## Versions
73+
74+
- Polkadot SDK: ...
75+
- Rust: ...
76+
77+
## Compatibility
78+
79+
- SH Backend vX.Y.Z → Pallets/Client versions: ...
80+
- SDK vX.Y.Z → Backend/Client/Pallets versions: ...
81+
82+
## Upgrade Guide
83+
84+
- Step 1: ...
85+
- Step 2: ...
86+
- Rollback notes: ...

‎RELEASE_PROCESS.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
## StorageHub Release Process
2+
3+
This document standardises how to cut a StorageHub release using GitHub tools. It assumes CI already validates pushes to `main`.
4+
5+
### Branching and Tagging
6+
7+
- Create a long-lived release branch per minor series: `release/v0.1`
8+
- Tag releases from this branch: `v0.1.0`, `v0.1.1`, ...
9+
10+
### Steps
11+
12+
1. Create the release branch
13+
14+
```bash
15+
git checkout main && git pull
16+
git checkout -b release/v0.1
17+
git push origin release/v0.1
18+
```
19+
20+
2. Audit changes since last tagged commit
21+
22+
- Identify the base commit (last tag). For the first release, base is `05d269a26d11c1ed8a6d917b3e08ff3b5d3d4b22`.
23+
- Review commits and merged PRs since base.
24+
25+
Useful commands:
26+
27+
```bash
28+
git log --oneline 05d269a26d11c1ed8a6d917b3e08ff3b5d3d4b22..HEAD
29+
git diff --stat 05d269a26d11c1ed8a6d917b3e08ff3b5d3d4b22..HEAD
30+
```
31+
32+
3. Migration and upgrade checks
33+
34+
- RocksDB
35+
- File storage (`client/file-manager`), forest storage (`client/forest-manager`, `client/src/forest_storage.rs`), and state store (`client/blockchain-service`, `client/src/download_state_store.rs`).
36+
- Document any schema/key/encoding changes and required actions.
37+
- Indexer PostgresDB
38+
- Check `/client/indexer-db/migrations` for new migrations AND cross-check code changes in `client/indexer-db` in case any migration was missed.
39+
- Runtime
40+
- Document runtime `spec_version`, any storage migrations, and constant changes.
41+
- Pallets
42+
- Check changes in `/pallets` directory. Pay special attention to changes in runtime constants and storage migrations.
43+
44+
4. Fill release notes
45+
46+
- Copy `RELEASE_NOTES_TEMPLATE.md` to `RELEASE_NOTES_vX.Y.Z.md` and complete all sections (DB/runtime, scripts, client behaviour/initialisation, versions, compatibility, PRs/commits).
47+
48+
5. Publish the release via GitHub UI
49+
50+
- Go to: GitHub → `storage-hub` repository → Create new release.
51+
- Target: `release/vX.Y`.
52+
- Tag: `vX.Y.Z` (create new tag on publish).
53+
- Title: `StorageHub vX.Y.Z`.
54+
- Body: Paste `RELEASE_NOTES_vX.Y.Z.md` contents.
55+
- Publish release.
56+
57+
Notes:
58+
59+
- Publishing a release triggers the CI workflow `.github/workflows/release-publish.yml` to:
60+
- Build and push the SH Backend Docker image to DockerHub with the tag (e.g., `vX.Y.Z`).
61+
- Build and publish npm packages for `sdk/`, `api-augment/`, and `types-bundle/`.
62+
63+
6. After the release
64+
65+
- If needed, cherry-pick hotfixes to `release/vX.Y` and repeat (tag `vX.Y.Z`, etc.).
66+
67+
### Compatibility Matrix (to include in notes)
68+
69+
- SH Backend Docker Image → compatible with which pallets and client code version.
70+
- SH SDK (npm) → compatible with which backend, client, and pallets code version.
71+
72+
### Versions to document (to include in notes)
73+
74+
- Polkadot SDK overall version (e.g., `polkadot-stable2412-6`).
75+
- Rust toolchain version from `rust-toolchain.toml` (e.g., `1.87`).

0 commit comments

Comments
 (0)