Merge pull request #1 from Relism/feature/ci-cd/setup

ci: setup CI/CD pipelines, versioning and agent guidelines
2026-05-11 14:24:13 +02:00
parent f310646868 945633e5bd
commit 8af81ac28c
22 changed files with 544 additions and 15 deletions
@@ -0,0 +1,17 @@
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
+          http://maven.apache.org/xsd/maven-1.0.0.xsd">
+    <servers>
+        <server>
+            <id>Personal</id>
+            <username>${env.MAVEN_USERNAME}</username>
+            <password>${env.MAVEN_PASSWORD}</password>
+        </server>
+        <server>
+            <id>Personal-snapshots</id>
+            <username>${env.MAVEN_USERNAME}</username>
+            <password>${env.MAVEN_PASSWORD}</password>
+        </server>
+    </servers>
+</settings>
@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+      - 'feature/**'
+      - 'fix/**'
+      - 'hotfix/**'
+    tags-ignore:
+      - 'v*'
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Build & Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Temurin 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+          server-id: Personal
+          server-username: MAVEN_USERNAME
+          server-password: MAVEN_PASSWORD
+
+      - name: Build and test
+        run: mvn -B --settings .github/settings.xml clean verify
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+
+      - name: Publish test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: test-results
+          path: '**/target/surefire-reports/*.xml'
+          retention-days: 7
@@ -0,0 +1,69 @@
+name: Prepare Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version (e.g. 2.0.0)'
+        required: true
+        type: string
+      next_version:
+        description: 'Next development version without -SNAPSHOT (e.g. 2.1.0)'
+        required: true
+        type: string
+
+jobs:
+  prepare:
+    name: Bump, Tag & Push
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Set up Temurin 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Set release version
+        run: mvn -B --settings .github/settings.xml versions:set -DnewVersion=${{ inputs.version }}
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+
+      - name: Commit release version
+        run: |
+          git add -A
+          git commit -m "chore(release): ${{ inputs.version }}"
+
+      - name: Tag release
+        run: git tag v${{ inputs.version }}
+
+      - name: Set next snapshot version
+        run: mvn -B --settings .github/settings.xml versions:set -DnewVersion=${{ inputs.next_version }}-SNAPSHOT
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+
+      - name: Commit next snapshot version
+        run: |
+          git add -A
+          git commit -m "chore(release): prepare ${{ inputs.next_version }}-SNAPSHOT"
+
+      - name: Push commits and tag
+        run: |
+          git push origin master
+          git push origin v${{ inputs.version }}
@@ -0,0 +1,136 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    name: Build, Sign, Deploy & Publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from tag
+        id: version
+        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> $GITHUB_OUTPUT
+
+      - name: Set up Temurin 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+
+      - name: Import GPG key
+        run: |
+          echo "${{ secrets.GPG_PRIVATE_KEY }}" | gpg --batch --import
+          GPG_KEY_ID=$(gpg --list-secret-keys --with-colons | grep '^sec' | cut -d: -f5 | head -1)
+          echo "GPG_KEY_ID=$GPG_KEY_ID" >> $GITHUB_ENV
+
+      - name: Build, sign and deploy to releases
+        run: |
+          mvn -B --settings .github/settings.xml \
+            -DperformRelease=true \
+            -Dgpg.keyname=$GPG_KEY_ID \
+            clean deploy
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+
+      - name: Generate aggregated JavaDoc
+        run: |
+          mvn -B --settings .github/settings.xml \
+            -pl flash,flash-extensions -am \
+            javadoc:aggregate -DskipTests
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
+
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+          path: gh-pages-out
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Copy JavaDoc to versioned folder
+        run: |
+          VERSION=${{ steps.version.outputs.VERSION }}
+          mkdir -p gh-pages-out/javadoc/$VERSION
+          cp -r target/reports/apidocs/. gh-pages-out/javadoc/$VERSION/
+          rm -rf gh-pages-out/latest
+          mkdir -p gh-pages-out/latest
+          cp -r target/reports/apidocs/. gh-pages-out/latest/
+
+      - name: Regenerate index.html
+        run: |
+          cd gh-pages-out
+          python3 - <<'EOF'
+          import os, re
+
+          versions = sorted(
+              [d for d in os.listdir("javadoc") if os.path.isdir(f"javadoc/{d}")],
+              key=lambda v: [int(x) for x in re.sub(r'[^0-9.]', '', v).split('.') if x],
+              reverse=True
+          )
+
+          rows = "\n".join(
+              f'      <li><a href="javadoc/{v}/index.html">{v}</a></li>'
+              for v in versions
+          )
+
+          html = f"""<!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <title>Flash JavaDoc</title>
+            <style>
+              body {{ font-family: sans-serif; max-width: 600px; margin: 4rem auto; }}
+              h1 {{ font-size: 1.6rem; }}
+              ul {{ line-height: 2; }}
+              a {{ color: #0070f3; text-decoration: none; }}
+              a:hover {{ text-decoration: underline; }}
+            </style>
+          </head>
+          <body>
+            <h1>Flash — JavaDoc</h1>
+            <p><a href="latest/index.html">&#8594; Latest</a></p>
+            <h2>All versions</h2>
+            <ul>
+          {rows}
+            </ul>
+          </body>
+          </html>"""
+
+          with open("index.html", "w") as f:
+              f.write(html)
+          print(f"index.html generated with {len(versions)} versions: {versions}")
+          EOF
+
+      - name: Push gh-pages
+        run: |
+          cd gh-pages-out
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --cached --quiet || git commit -m "docs(javadoc): release ${{ steps.version.outputs.VERSION }}"
+          git push origin gh-pages
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: v${{ steps.version.outputs.VERSION }}
+          name: v${{ steps.version.outputs.VERSION }}
+          generate_release_notes: true
+          draft: false
+          prerelease: false
@@ -0,0 +1,30 @@
+name: Publish Snapshot
+
+on:
+  push:
+    branches:
+      - master
+    tags-ignore:
+      - 'v*'
+
+jobs:
+  snapshot:
+    name: Deploy Snapshot
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Temurin 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+          cache: maven
+
+      - name: Deploy snapshot
+        run: mvn -B --settings .github/settings.xml clean deploy -DskipTests
+        env:
+          MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
+          MAVEN_PASSWORD: ${{ secrets.MAVEN_PASSWORD }}
@@ -1,4 +1,7 @@
 target/
+*.versionsBackup
+.mvn/timing.properties
+*.class
 !.mvn/wrapper/maven-wrapper.jar
 !**/src/main/**/target/
 !**/src/test/**/target/
@@ -0,0 +1,118 @@
+# Flash — Agent Guidelines
+
+This document defines the conventions and rules that all agents (AI or human) must follow
+when working on this repository. Read it entirely before making any change.
+
+---
+
+## Git Workflow
+
+### Branch Naming
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| New feature | `feature/<scope>/<short-description>` | `feature/ext-oidc/pkce-support` |
+| Bug fix | `fix/<scope>/<short-description>` | `fix/core/router-npe` |
+| Hotfix on released version | `hotfix/<version>/<short-description>` | `hotfix/2.0.1/auth-bypass` |
+| CI/infra changes | `feature/ci/<short-description>` | `feature/ci/add-snapshot-workflow` |
+
+Rules:
+- Always branch from `master`.
+- Branch names are lowercase, words separated by `-`.
+- Never push directly to `master`.
+- Never create `develop`, `release/*`, or any other long-lived branch.
+
+### Commit Messages — Conventional Commits
+
+Format: `<type>(<scope>): <short description>`
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Code change without feature/fix |
+| `test` | Adding or updating tests |
+| `docs` | Documentation only |
+| `chore` | Build, deps, tooling — no production code |
+| `ci` | Changes to GitHub Actions workflows |
+
+Allowed scopes: `core`, `ext-jackson`, `ext-openapi`, `ext-oidc`, `ext-routeviewer`,
+`ext-view-core`, `ext-view-jte`, `ext-view-thymeleaf`, `ext-limiter`, `ext-web-bundler`,
+`ext-data-core`, `ext-data-jdbc`, `ext-data-hibernate`, `release`, `deps`, `ci`.
+
+Examples:
+```
+feat(ext-oidc): add PKCE support
+fix(core): fix NPE in RouteHandler when path is null
+chore(deps): upgrade jackson to 2.18.0
+ci: add timeout to snapshot workflow
+chore(release): 2.1.0
+```
+
+### Pull Requests
+
+- Every branch must be merged via PR, never with a direct push.
+- PR title must follow Conventional Commits format.
+- CI (`ci.yml`) must be green before merging.
+- Squash merge is preferred for `feature/*` and `fix/*` to keep history clean.
+- Merge commit is preferred for hotfixes (preserves the fix commit intact).
+
+---
+
+## Versioning
+
+- All modules share a single version defined in the root `pom.xml` (`flash-parent`).
+- Never change the version in child POMs — always and only in the parent.
+- Current scheme: `MAJOR.MINOR.PATCH`
+  - MAJOR: breaking API changes
+  - MINOR: new backward-compatible features
+  - PATCH: backward-compatible bug fixes on an already-released version
+- During development, master always carries a `-SNAPSHOT` version.
+- **Never manually edit the version** — versions are bumped exclusively by the
+  `prepare-release` GitHub Actions workflow.
+
+### Release Process (for maintainers only)
+
+1. Ensure `master` is green (CI passing).
+2. Go to GitHub Actions → `Prepare Release` → `Run workflow`.
+3. Input `version` (e.g. `2.1.0`) and `next_version` (e.g. `2.2.0`).
+4. The workflow handles everything: bump, commit, tag, push.
+5. The `release` workflow then triggers automatically on the tag.
+
+---
+
+## Maven & Module Structure
+
+- Root POM: `flash-parent` — defines all dependency versions and plugin config.
+- `flash` module: the core framework JAR.
+- `flash-extensions` POM: aggregator for all extension modules.
+- Extensions live under `flash-extensions/flash-ext-*/`.
+- When adding a new extension:
+  1. Add the module to `flash-extensions/pom.xml` `<modules>`.
+  2. Add the dependency to `flash-extensions/pom.xml` `<dependencyManagement>`.
+  3. Add the dependency to the root `pom.xml` `<dependencyManagement>`.
+  4. Do **not** declare a `<version>` in the new module's POM — it inherits from the parent.
+
+---
+
+## CI/CD Pipelines
+
+| Workflow | Trigger | What it does |
+|----------|---------|--------------|
+| `ci.yml` | Push to any branch, PR to master | Compile + test — required gate |
+| `snapshot.yml` | Push to `master` | Deploy `-SNAPSHOT` to `maven.relism.dev/snapshots` |
+| `prepare-release.yml` | Manual `workflow_dispatch` | Bump version, commit, tag, push |
+| `release.yml` | Push of tag `v*` | GPG sign, deploy to `/releases`, JavaDoc to GitHub Pages, GitHub Release |
+
+**Agents must never manually trigger `prepare-release` or modify version strings.**
+
+---
+
+## What Agents Must NOT Do
+
+- Push directly to `master` or `gh-pages`.
+- Manually edit `<version>` tags in any POM.
+- Add new `<repositories>` or `<distributionManagement>` entries without explicit instruction.
+- Modify `.github/workflows/*.yml` files without explicit instruction.
+- Commit generated files (`target/`, `*.class`, `*.versionsBackup`).
+- Use `git push --force` on any branch.
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-data-core</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-data-hibernate</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-data-jdbc</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-jackson</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-limiter</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-oidc</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-openapi</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-routeviewer</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-view-core</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-view-jte</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-view-thymeleaf</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-extensions</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-ext-web-bundler</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-parent</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash-extensions</artifactId>
@@ -7,7 +7,7 @@
    <parent>
        <groupId>dev.relism</groupId>
        <artifactId>flash-parent</artifactId>
-        <version>1.1-indev6</version>
+        <version>2.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>flash</artifactId>
@@ -6,7 +6,7 @@

    <groupId>dev.relism</groupId>
    <artifactId>flash-parent</artifactId>
-    <version>1.1-indev6</version>
+    <version>2.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <modules>
@@ -19,6 +19,10 @@
            <id>Personal</id>
            <url>https://maven.relism.dev/releases</url>
        </repository>
+        <snapshotRepository>
+            <id>Personal-snapshots</id>
+            <url>https://maven.relism.dev/snapshots</url>
+        </snapshotRepository>
    </distributionManagement>

    <properties>
@@ -27,6 +31,10 @@
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <lombok.version>1.18.44</lombok.version>
        <slf4j.version>2.0.16</slf4j.version>
+        <maven.javadoc.plugin.version>3.11.2</maven.javadoc.plugin.version>
+        <maven.source.plugin.version>3.3.1</maven.source.plugin.version>
+        <maven.gpg.plugin.version>3.2.8</maven.gpg.plugin.version>
+        <maven.versions.plugin.version>2.18.0</maven.versions.plugin.version>
    </properties>

    <repositories>
@@ -141,8 +149,109 @@
                        </annotationProcessorPaths>
                    </configuration>
                </plugin>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-source-plugin</artifactId>
+                    <version>${maven.source.plugin.version}</version>
+                </plugin>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-javadoc-plugin</artifactId>
+                    <version>${maven.javadoc.plugin.version}</version>
+                    <configuration>
+                        <source>${maven.compiler.source}</source>
+                        <encoding>${project.build.sourceEncoding}</encoding>
+                        <doclint>none</doclint>
+                        <failOnError>true</failOnError>
+                    </configuration>
+                </plugin>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-gpg-plugin</artifactId>
+                    <version>${maven.gpg.plugin.version}</version>
+                </plugin>
+                <plugin>
+                    <groupId>org.codehaus.mojo</groupId>
+                    <artifactId>versions-maven-plugin</artifactId>
+                    <version>${maven.versions.plugin.version}</version>
+                    <configuration>
+                        <generateBackupPoms>false</generateBackupPoms>
+                    </configuration>
+                </plugin>
+                <plugin>
+                    <groupId>org.apache.maven.plugins</groupId>
+                    <artifactId>maven-deploy-plugin</artifactId>
+                    <version>3.1.2</version>
+                </plugin>
            </plugins>
        </pluginManagement>
    </build>

+    <profiles>
+        <profile>
+            <id>attach-artifacts</id>
+            <activation>
+                <file>
+                    <exists>src/main/java</exists>
+                </file>
+            </activation>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-source-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <id>attach-sources</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>jar-no-fork</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-javadoc-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <id>attach-javadocs</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>jar</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+        <profile>
+            <id>sign-artifacts</id>
+            <activation>
+                <property>
+                    <name>performRelease</name>
+                    <value>true</value>
+                </property>
+            </activation>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-gpg-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <id>sign-artifacts</id>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>sign</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+
 </project>