Skip to content

Commit abaa99f

Browse files
acx10acx10
authored
Merge pull request #2396 from booklore-app/release/1.18
Release v1.18.0
2 parents bde772e + b95248e commit abaa99f

File tree

723 files changed

+60166
-25042
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

723 files changed

+60166
-25042
lines changed

‎.github/RELEASE_WORKFLOW.md‎

Lines changed: 357 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,357 @@
1+
# Release Workflow
2+
3+
This document describes the branch strategy, CI/CD pipelines, and release process for Booklore.
4+
5+
## Branch Strategy
6+
7+
```
8+
master Stable releases only. Tagged with vX.Y.Z
9+
↑
10+
release/X.Y Release stabilization. RC builds published here
11+
↑
12+
develop Active development. All feature PRs merge here
13+
```
14+
15+
| Branch | Purpose | Stability |
16+
|--------|---------|-----------|
17+
| `master` | Production releases | Stable |
18+
| `release/X.Y` | Release candidates, bug fixes | Stabilizing |
19+
| `develop` | New features, active development | Unstable |
20+
21+
## CI/CD Pipelines
22+
23+
### 1. Develop Pipeline (`develop-pipeline.yml`)
24+
25+
**Triggers:**
26+
- Push to `develop`
27+
- PRs targeting `develop`, `release/**`, or `master`
28+
29+
**Actions:**
30+
- Flyway migration check
31+
- Backend tests (Gradle)
32+
- Frontend tests (Angular/Vitest)
33+
- Docker build and push (for pushes and internal PRs)
34+
35+
**Image Tags:** `develop-{sha}`, `pr-{number}-{sha}`
36+
37+
---
38+
39+
### 2. Release Pipeline (`release-pipeline.yml`)
40+
41+
**Triggers:**
42+
- Push to `release/**` branches
43+
- PRs targeting `release/**` branches
44+
45+
**Actions:**
46+
- Flyway migration check (against `master`)
47+
- Backend and frontend tests
48+
- Docker build and push with RC tags
49+
50+
**Image Tags:** `v1.18.0-rc.1`, `v1.18.0-rc.2`, `release-1.18-{sha}`
51+
52+
**Validations:**
53+
- Branch name must be `release/X.Y` or `release/X.Y.Z`
54+
- Version must be newer than latest tag
55+
- Rejects suspicious version jumps (typo protection)
56+
57+
---
58+
59+
### 3. Master Tag Pipeline (`master-pipeline.yml`)
60+
61+
**Triggers:**
62+
- Push of tags matching `v*`
63+
64+
**Actions:**
65+
- Tag format validation
66+
- Flyway migration check
67+
- Backend and frontend tests
68+
- Docker build and push
69+
- GitHub Release publication (publishes the draft release)
70+
71+
**Image Tags:** `v1.18.0`, `latest` (stable releases only)
72+
73+
**Validations:**
74+
- Tag must be valid semver (`vX.Y.Z` or `vX.Y.Z-prerelease.N`)
75+
- Version must be newer than latest stable tag
76+
- Rejects suspicious version jumps (typo protection)
77+
- Blocks prereleases if stable version already exists
78+
79+
---
80+
81+
### 4. Draft Release Pipeline (`draft-release.yml`)
82+
83+
**Triggers:**
84+
- Push to `master`
85+
86+
**Actions:**
87+
- Updates draft GitHub Release with changelog from merged PRs
88+
- Categorizes changes based on PR labels (feature, bug, enhancement, etc.)
89+
- Auto-resolves next version based on labels (major/minor/patch)
90+
91+
**Configuration:** `.github/release-drafter.yml`
92+
93+
**How it works:**
94+
1. Each PR merged to `master` triggers this workflow
95+
2. Release-drafter accumulates changes into a draft release
96+
3. When you push a `v*` tag, the master-pipeline publishes the draft
97+
98+
**Label → Version mapping:**
99+
| Label | Version Bump |
100+
|-------|--------------|
101+
| `major` | X.0.0 |
102+
| `minor` | 0.X.0 |
103+
| `patch` | 0.0.X |
104+
105+
**Label → Changelog category:**
106+
| Labels | Category |
107+
|--------|----------|
108+
| `feature` | New Features |
109+
| `enhancement` | Enhancements |
110+
| `bug`, `fix` | Bug Fixes |
111+
| `refactor`, `cleanup`, `chore` | Refactoring & Maintenance |
112+
| `dependencies`, `deps` | Dependencies |
113+
| `ci`, `cd`, `workflow` | CI/CD |
114+
| `docs`, `documentation` | Documentation |
115+
116+
PRs with the `skip changelog` label are excluded from release notes.
117+
118+
---
119+
120+
## Release Flow Diagram
121+
122+
```
123+
v1.17.0 (current)
124+
│
125+
develop ────●────●────●────●─────────────────●──▶ (continues)
126+
│ ↑
127+
│ (1) cut branch │ (5) merge back
128+
▼ │
129+
release/1.18 ──●──●──●────────────────┼──▶ (delete)
130+
│ │ │ │
131+
▼ ▼ ▼ │
132+
rc.1 rc.2 rc.3 │
133+
│
134+
master ──────────────────────────────────────●──▶
135+
│
136+
(4) tag v1.18.0
137+
│
138+
▼
139+
Docker: v1.18.0 + latest
140+
GitHub Release created
141+
```
142+
143+
## Step-by-Step Release Process
144+
145+
### Phase 1: Cut Release Branch
146+
147+
When `develop` is feature-complete for the release:
148+
149+
```bash
150+
git checkout develop && git pull
151+
git checkout -b release/1.18
152+
git push -u origin release/1.18
153+
```
154+
155+
**What happens:**
156+
- Release pipeline runs tests
157+
- Publishes `v1.18.0-rc.1` to Docker Hub and GHCR
158+
- RC number increments with each subsequent push
159+
160+
---
161+
162+
### Phase 2: Stabilize (Optional)
163+
164+
If bugs are found during RC testing, fix them on the release branch:
165+
166+
```bash
167+
git checkout release/1.18
168+
git checkout -b fix/critical-bug
169+
# ... make fixes ...
170+
git commit -m "Fix critical bug in authentication"
171+
git push -u origin fix/critical-bug
172+
173+
# Create PR targeting the release branch
174+
gh pr create --base release/1.18 --title "Fix critical bug"
175+
gh pr merge --squash
176+
```
177+
178+
**What happens:**
179+
- Each merge to `release/1.18` publishes a new RC (`v1.18.0-rc.2`, `rc.3`, etc.)
180+
- Testers can pull specific RC versions to validate fixes
181+
182+
---
183+
184+
### Phase 3: Merge to Master
185+
186+
When the RC is validated and stable:
187+
188+
```bash
189+
# Create PR from release branch to master
190+
gh pr create --base master --head release/1.18 --title "Release v1.18.0"
191+
192+
# After approval, merge (use merge commit, not squash)
193+
gh pr merge --merge
194+
```
195+
196+
**What happens:**
197+
- Develop pipeline runs tests on the PR
198+
- Merge commit lands on `master`
199+
- No release is published yet (waiting for tag)
200+
201+
---
202+
203+
### Phase 4: Tag and Release
204+
205+
Create the release tag to trigger the final release:
206+
207+
```bash
208+
git checkout master && git pull
209+
git tag v1.18.0
210+
git push origin v1.18.0
211+
```
212+
213+
**What happens:**
214+
- Master Tag pipeline validates the tag
215+
- Runs full test suite
216+
- Builds and pushes Docker images: `v1.18.0` + `latest`
217+
- Publishes the draft GitHub Release (created by `draft-release.yml`) with changelog
218+
219+
---
220+
221+
### Phase 5: Post-Release Cleanup
222+
223+
Sync the release back to `develop` and clean up:
224+
225+
```bash
226+
# Merge master back to develop (includes any RC fixes)
227+
git checkout develop && git pull
228+
git merge master
229+
git push origin develop
230+
231+
# Delete the release branch
232+
git push origin --delete release/1.18
233+
git branch -d release/1.18
234+
```
235+
236+
---
237+
238+
## Quick Reference Commands
239+
240+
### New Minor Release (v1.17.0 → v1.18.0)
241+
242+
```bash
243+
# Cut release
244+
git checkout develop && git pull
245+
git checkout -b release/1.18
246+
git push -u origin release/1.18
247+
248+
# When stable, merge to master
249+
gh pr create --base master --head release/1.18 --title "Release v1.18.0"
250+
gh pr merge --merge
251+
252+
# Tag release
253+
git checkout master && git pull
254+
git tag v1.18.0
255+
git push origin v1.18.0
256+
257+
# Cleanup
258+
git checkout develop && git pull && git merge master && git push
259+
git push origin --delete release/1.18
260+
git branch -d release/1.18
261+
```
262+
263+
### New Patch Release (v1.18.0 → v1.18.1)
264+
265+
```bash
266+
# Cut release from master (or existing release branch)
267+
git checkout master && git pull
268+
git checkout -b release/1.18
269+
git push -u origin release/1.18
270+
271+
# Cherry-pick or fix bugs, then merge and tag
272+
gh pr create --base master --head release/1.18 --title "Release v1.18.1"
273+
gh pr merge --merge
274+
git checkout master && git pull
275+
git tag v1.18.1
276+
git push origin v1.18.1
277+
278+
# Cleanup
279+
git checkout develop && git pull && git merge master && git push
280+
git push origin --delete release/1.18
281+
```
282+
283+
### Hotfix (urgent production fix)
284+
285+
```bash
286+
# Create hotfix branch from master
287+
git checkout master && git pull
288+
git checkout -b hotfix/1.18.1
289+
# ... make urgent fix ...
290+
git commit -m "Fix critical security issue"
291+
git push -u origin hotfix/1.18.1
292+
293+
# Merge to master and tag
294+
gh pr create --base master --head hotfix/1.18.1 --title "Hotfix v1.18.1"
295+
gh pr merge --merge
296+
git checkout master && git pull
297+
git tag v1.18.1
298+
git push origin v1.18.1
299+
300+
# Merge fix to develop
301+
git checkout develop && git pull && git merge master && git push
302+
git push origin --delete hotfix/1.18.1
303+
```
304+
305+
---
306+
307+
## Version Validation Rules
308+
309+
The pipelines enforce these rules to prevent mistakes:
310+
311+
| Rule | Example | Result |
312+
|------|---------|--------|
313+
| No backwards versions | `v1.17.0` after `v1.18.0` | Blocked |
314+
| No duplicate stable versions | `v1.18.0` after `v1.18.0` | Blocked |
315+
| No prerelease after stable | `v1.18.0-rc.1` after `v1.18.0` | Blocked |
316+
| Major jump ≤ 1 | `v3.0.0` after `v1.18.0` | Blocked |
317+
| Minor jump ≤ 5 | `v1.25.0` after `v1.18.0` | Blocked |
318+
| Patch jump ≤ 10 | `v1.18.15` after `v1.18.0` | Blocked |
319+
320+
These rules catch typos like `release/1.118` instead of `release/1.18`.
321+
322+
---
323+
324+
## Docker Image Tags
325+
326+
| Event | Tags Published |
327+
|-------|---------------|
328+
| Push to `develop` | `develop-abc1234` |
329+
| PR #42 | `pr-42-abc1234` |
330+
| Push to `release/1.18` | `v1.18.0-rc.1`, `release-1.18-abc1234` |
331+
| Tag `v1.18.0` | `v1.18.0`, `latest` |
332+
| Tag `v1.18.1-rc.1` | `v1.18.1-rc.1` (no `latest`) |
333+
334+
---
335+
336+
## FAQ
337+
338+
**Q: Can I have multiple release branches simultaneously?**
339+
A: Yes. `release/1.18` and `release/1.19` can coexist. Each gets independent RC numbers.
340+
341+
**Q: What if I need to release a patch for an older version?**
342+
A: Create `release/1.17` from the `v1.17.0` tag, make fixes, and tag `v1.17.1`.
343+
344+
**Q: Why use merge commits instead of squash for release PRs?**
345+
A: Merge commits preserve the full history of RC fixes, making it easier to track what changed.
346+
347+
**Q: Can I skip the RC phase for urgent fixes?**
348+
A: Yes. For hotfixes, you can merge directly to master and tag. The release pipeline is optional.
349+
350+
**Q: What happens if I push a tag that fails validation?**
351+
A: The pipeline fails before publishing anything. Delete the tag (`git push --delete origin v1.18.0`), fix the issue, and re-tag.
352+
353+
**Q: How do I preview release notes before publishing?**
354+
A: Go to GitHub Releases. The draft release is automatically updated as PRs merge to `master`. Review and edit the draft before tagging.
355+
356+
**Q: Why don't I see changes in the draft release?**
357+
A: Ensure PRs have appropriate labels (`feature`, `bug`, `enhancement`, etc.). PRs without recognized labels still appear but won't be categorized. PRs with `skip changelog` label are excluded.

‎.github/workflows/develop-pipeline.yml‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,17 @@ on:
66
- develop
77
pull_request:
88
branches:
9-
- '**'
10-
11-
concurrency:
12-
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
13-
cancel-in-progress: true
9+
- develop
10+
- 'release/**'
11+
- master
1412

1513
jobs:
1614
migration-check:
1715
name: Flyway Migration Check
1816
uses: ./.github/workflows/migrations-check.yml
1917
with:
20-
base_ref: 'develop'
18+
# For PRs, compare against target branch; for pushes, compare against develop
19+
base_ref: ${{ github.event_name == 'pull_request' && github.base_ref || 'develop' }}
2120
head_ref: 'HEAD'
2221

2322
backend-tests:
@@ -209,4 +208,5 @@ jobs:
209208
type=registry,ref=ghcr.io/booklore-app/booklore:buildcache
210209
cache-to: |
211210
type=gha,mode=max
212-
type=registry,ref=ghcr.io/booklore-app/booklore:buildcache,mode=max
211+
type=registry,ref=ghcr.io/booklore-app/booklore:buildcache,mode=max
212+

0 commit comments

Comments
 (0)