Skip to content

Commit cfdb94f

Browse files
bercianorbercianor
authored
docs: release update and documentation (#717)
* docs: add release workflow documentation * feat: publish sql-template to maven
1 parent 8aee497 commit cfdb94f

File tree

4 files changed

+354
-11
lines changed

4 files changed

+354
-11
lines changed

‎.github/workflows/release.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -291,6 +291,19 @@ jobs:
291291
FLAMINGOCK_JRELEASER_GPG_SECRET_KEY: ${{ secrets.FLAMINGOCK_JRELEASER_GPG_SECRET_KEY }}
292292
FLAMINGOCK_JRELEASER_GPG_PASSPHRASE: ${{ secrets.FLAMINGOCK_JRELEASER_GPG_PASSPHRASE }}
293293

294+
flamingock-sql-template:
295+
needs: [ build ]
296+
uses: ./.github/workflows/module-release-graalvm.yml
297+
with:
298+
module: flamingock-sql-template
299+
secrets:
300+
FLAMINGOCK_JRELEASER_GITHUB_TOKEN: ${{ secrets.FLAMINGOCK_JRELEASER_GITHUB_TOKEN }}
301+
FLAMINGOCK_JRELEASER_MAVENCENTRAL_USERNAME: ${{ secrets.FLAMINGOCK_JRELEASER_MAVENCENTRAL_USERNAME }}
302+
FLAMINGOCK_JRELEASER_MAVENCENTRAL_PASSWORD: ${{ secrets.FLAMINGOCK_JRELEASER_MAVENCENTRAL_PASSWORD }}
303+
FLAMINGOCK_JRELEASER_GPG_PUBLIC_KEY: ${{ secrets.FLAMINGOCK_JRELEASER_GPG_PUBLIC_KEY }}
304+
FLAMINGOCK_JRELEASER_GPG_SECRET_KEY: ${{ secrets.FLAMINGOCK_JRELEASER_GPG_SECRET_KEY }}
305+
FLAMINGOCK_JRELEASER_GPG_PASSPHRASE: ${{ secrets.FLAMINGOCK_JRELEASER_GPG_PASSPHRASE }}
306+
294307
general-util:
295308
needs: [ build ]
296309
uses: ./.github/workflows/module-release-graalvm.yml
@@ -378,6 +391,7 @@ jobs:
378391
sql-target-system,
379392
dynamodb-target-system,
380393
couchbase-target-system,
394+
flamingock-sql-template,
381395
general-util,
382396
test-util,
383397
mongodb-util,

‎buildSrc/src/main/kotlin/flamingock.project-structure.gradle.kts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,7 @@ val targetSystemProjects = setOf(
4040
)
4141

4242
val templateProjects = setOf(
43-
"flamingock-sql-template",
44-
"flamingock-mongodb-sync-template"
43+
"flamingock-sql-template"
4544
)
4645

4746
val utilProjects = setOf(

‎docs/WORKFLOW_RELEASE_DOCUMENTATION.md‎

Lines changed: 339 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,339 @@
1+
# Comprehensive Documentation of Flamingock Release Workflow
2+
3+
## Table of Contents
4+
1. [Overview](#overview)
5+
2. [Main Workflow Structure](#main-workflow-structure)
6+
3. [Module Release Workflow](#module-release-workflow)
7+
4. [GitHub Release Workflow](#github-release-workflow)
8+
5. [Useful Commands for Local Development](#useful-commands-for-local-development)
9+
6. [jReleaser Configuration](#jreleaser-configuration)
10+
7. [Detailed jReleaser Steps](#detailed-jreleaser-steps)
11+
8. [Local Testing Commands](#local-testing-commands)
12+
9. [Infrastructure Scripts](#infrastructure-scripts)
13+
14+
---
15+
16+
## Overview
17+
18+
The Flamingock release system is designed to publish 25 different modules to Maven Central and create releases on GitHub. It uses jReleaser v1.15.0 as the main tool to manage the publication process.
19+
20+
### Modules to Publish
21+
22+
**Core (5 modules):**
23+
- flamingock-core
24+
- flamingock-core-commons
25+
- flamingock-core-api
26+
- flamingock-processor
27+
- flamingock-graalvm
28+
29+
**Cloud (2 modules):**
30+
- flamingock-cloud
31+
- flamingock-cloud-bom
32+
33+
**Community (6 modules):**
34+
- flamingock-community
35+
- flamingock-community-bom
36+
- flamingock-auditstore-mongodb-sync
37+
- flamingock-auditstore-couchbase
38+
- flamingock-auditstore-dynamodb
39+
- flamingock-importer
40+
41+
**Plugins (1 module):**
42+
- flamingock-springboot-integration
43+
44+
**Target Systems (6 modules):**
45+
- nontransactional-target-system
46+
- mongodb-sync-target-system
47+
- mongodb-springdata-target-system
48+
- sql-target-system
49+
- dynamodb-target-system
50+
- couchbase-target-system
51+
52+
**Templates (2 modules, but not published for now):**
53+
- flamingock-sql-template
54+
- flamingock-mongodb-sync-template
55+
56+
**Utils (5 modules):**
57+
- general-util
58+
- test-util
59+
- mongodb-util
60+
- dynamodb-util
61+
- couchbase-util
62+
63+
---
64+
65+
## Main Workflow Structure
66+
67+
### File: `.github/workflows/release.yml`
68+
69+
The main workflow is structured in several jobs that run in sequence:
70+
71+
### 1. Job: `build`
72+
**Purpose:** Compilation and initial testing of the complete project
73+
74+
**Local equivalent command:**
75+
```bash
76+
./gradlew clean build
77+
```
78+
79+
### 2. Jobs: Module Release (25 jobs in parallel)
80+
81+
Each of the 25 modules is published individually using the reusable workflow `.github/workflows/module-release-graalvm.yml`
82+
83+
**Dependencies:**
84+
- Waits for the `build` job to finish successfully
85+
86+
### 3. Job: `github-release`
87+
88+
**Dependencies:**
89+
- Waits for all 25 modules to be successfully published to Maven Central
90+
91+
**Purpose:**
92+
- Create the release on GitHub with CLI artifacts
93+
94+
---
95+
96+
## Module Release Workflow
97+
98+
### File: `.github/workflows/module-release-graalvm.yml`
99+
100+
This workflow publishes an individual module to Maven Central.
101+
102+
### Step 1: Prepare local publication (staging)
103+
104+
**Local command:**
105+
```bash
106+
./gradlew publish -Pmodule={module-name}
107+
```
108+
109+
**Required environment variables:**
110+
```bash
111+
export JRELEASER_MAVENCENTRAL_USERNAME="your_username"
112+
export JRELEASER_MAVENCENTRAL_PASSWORD="your_token"
113+
```
114+
115+
**What it does:**
116+
- Compiles the module
117+
- Generates JARs (main, sources, javadoc)
118+
- Creates the POM file with complete metadata
119+
- Publishes to a local staging repository (`build/staging-deploy`)
120+
121+
### Step 2: Deploy to Maven Central with retries
122+
123+
**Local command:**
124+
```bash
125+
./infra/module-release-with-retry.sh {module-name} 5 20
126+
```
127+
128+
**Required environment variables:**
129+
```bash
130+
export JRELEASER_GITHUB_TOKEN="ghp_..."
131+
export JRELEASER_MAVENCENTRAL_USERNAME="your_username"
132+
export JRELEASER_MAVENCENTRAL_PASSWORD="your_token"
133+
export JRELEASER_GPG_PUBLIC_KEY="-----BEGIN PGP PUBLIC KEY BLOCK-----..."
134+
export JRELEASER_GPG_SECRET_KEY="-----BEGIN PGP PRIVATE KEY BLOCK-----..."
135+
export JRELEASER_GPG_PASSPHRASE="your_passphrase"
136+
```
137+
138+
**Parameters:**
139+
- Module name
140+
- 5 maximum attempts
141+
- 20 seconds wait between retries
142+
143+
**What it does:**
144+
- Executes `./gradlew jreleaserDeploy -Pmodule={module}` with retry logic
145+
- Signs artifacts with GPG
146+
- Generates checksums
147+
- Validates artifacts against Maven Central rules
148+
- Uploads bundle to Maven Central
149+
- Maven Central validates and publishes automatically
150+
151+
---
152+
153+
## GitHub Release Workflow
154+
155+
### File: `.github/workflows/github-release.yml`
156+
157+
**Local equivalent command:**
158+
```bash
159+
./gradlew jreleaserRelease --stacktrace
160+
```
161+
162+
**Required environment variables:**
163+
```bash
164+
export JRELEASER_GITHUB_TOKEN="ghp_..."
165+
export JRELEASER_GPG_PUBLIC_KEY="-----BEGIN PGP PUBLIC KEY BLOCK-----..."
166+
export JRELEASER_GPG_SECRET_KEY="-----BEGIN PGP PRIVATE KEY BLOCK-----..."
167+
export JRELEASER_GPG_PASSPHRASE="your_passphrase"
168+
```
169+
170+
**What it does:**
171+
- Creates a release on GitHub
172+
- Automatically generates the changelog (Conventional Commits)
173+
- Uploads CLI artifacts (zip, tar.gz, checksums)
174+
175+
**Internal process:**
176+
177+
1. **Compile CLI artifacts:**
178+
```bash
179+
./gradlew :cli:flamingock-cli:assemble
180+
```
181+
182+
Generates the following files in `cli/flamingock-cli/build/distributions/`:
183+
- `flamingock-cli.zip`
184+
- `flamingock-cli.tar.gz`
185+
- `checksums.txt`
186+
187+
2. **Copy artifacts to jReleaser directory:**
188+
189+
The `copyReleaseFiles` task (automatically executed as a dependency of `jreleaserRelease`) copies files from:
190+
- **Source:** `cli/flamingock-cli/build/distributions/`
191+
- **Destination:** `build/jreleaser/distributions/`
192+
193+
3. **Create release on GitHub:**
194+
195+
jReleaser uses files from the `build/jreleaser/distributions/` directory to:
196+
- Generate changelog by analyzing commits
197+
- Create/update the release on GitHub
198+
- Upload the 3 artifacts as release assets
199+
200+
---
201+
202+
## Useful Commands for Local Development
203+
204+
This section includes additional jReleaser and project commands that are useful during development and testing of the release process.
205+
206+
### 1. Generate CLI Artifacts
207+
208+
```bash
209+
# Compile and extract distribution
210+
./gradlew :cli:flamingock-cli:assemble
211+
cd cli/flamingock-cli/build/distributions/
212+
unzip flamingock-cli.zip
213+
cd flamingock-cli/
214+
215+
# Run CLI
216+
./bin/flamingock --help
217+
./bin/flamingock --version
218+
```
219+
220+
### 2. View jReleaser Configuration
221+
222+
```bash
223+
# Show complete jReleaser configuration
224+
./gradlew jreleaserConfig --stacktrace
225+
226+
# View required environment variables
227+
./gradlew jreleaserEnv --stacktrace
228+
```
229+
230+
### 3. Generate and View Changelog
231+
232+
```bash
233+
# Generate changelog without publishing (dry-run)
234+
./gradlew jreleaserChangelog --stacktrace
235+
236+
# Changelog is generated in: build/jreleaser/release/CHANGELOG.md
237+
cat build/jreleaser/release/CHANGELOG.md
238+
```
239+
240+
### 4. Validate Artifacts Before Deploy
241+
242+
```bash
243+
# Verify artifact checksums
244+
./gradlew jreleaserChecksum --stacktrace
245+
246+
# Validate GPG signatures
247+
./gradlew jreleaserSign --stacktrace
248+
```
249+
250+
### 5. Simulate Complete Release (Dry Run)
251+
252+
```bash
253+
# Simulate the entire process without actually executing anything
254+
./gradlew jreleaserRelease --dry-run --stacktrace
255+
256+
# See which files would be uploaded
257+
./gradlew jreleaserCatalog --stacktrace
258+
```
259+
260+
### 6. Individual vs Bundle Deploy
261+
262+
```bash
263+
# Deploy a specific module
264+
./gradlew jreleaserDeploy -Pmodule=flamingock-core --stacktrace
265+
266+
# Deploy a complete bundle (core, cloud, community, etc.)
267+
./gradlew jreleaserFullRelease -PreleaseBundle=core --stacktrace
268+
269+
# View all available modules (from code)
270+
# coreProjects, cloudProjects, communityProjects, pluginProjects,
271+
# targetSystemProjects, templateProjects, utilProjects
272+
```
273+
274+
### 7. Verify Publication Status
275+
276+
```bash
277+
# List modules and their publication status
278+
./gradlew publish -Pmodule=flamingock-core --dry-run
279+
280+
# System automatically verifies if already published on Maven Central
281+
# by querying: https://central.sonatype.com/api/v1/publisher/published
282+
```
283+
284+
### 8. Clean Release Artifacts
285+
286+
```bash
287+
# Clean only jReleaser artifacts
288+
rm -rf build/jreleaser/
289+
rm -rf cli/flamingock-cli/build/distributions/
290+
291+
# Clean publication staging
292+
rm -rf build/staging-deploy/
293+
rm -rf */build/staging-deploy/
294+
295+
# Complete cleanup
296+
./gradlew clean
297+
```
298+
299+
### 9. Advanced jReleaser Tasks
300+
301+
```bash
302+
# Assemble all distributions
303+
./gradlew jreleaserAssemble --stacktrace
304+
305+
# Package distributions
306+
./gradlew jreleaserPackage --stacktrace
307+
308+
# Publish without creating release
309+
./gradlew jreleaserPublish --stacktrace
310+
311+
# Full release (release + publish + announce)
312+
./gradlew jreleaserFullRelease --stacktrace
313+
314+
# Generate JSON configuration schema
315+
./gradlew jreleaserJsonSchema --stacktrace
316+
```
317+
318+
### 10. Verify Task Dependencies
319+
320+
```bash
321+
# View dependency tree of a task
322+
./gradlew jreleaserRelease --dry-run --stacktrace
323+
324+
# View all available jReleaser tasks
325+
./gradlew tasks --group=jreleaser
326+
```
327+
328+
### 11. Diagnostic Commands
329+
330+
```bash
331+
# Verify all environment variables are configured
332+
env | grep JRELEASER
333+
334+
# Check project version
335+
./gradlew properties | grep version
336+
337+
# List all project modules
338+
./gradlew projects | grep flamingock
339+
```

‎mave-release-guide.md‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

0 commit comments

Comments
 (0)