From 9c6ccaf8d9e5c16604d23f6be1dd98dbc8fe3b06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Dinis=20Ferreira?= <hello@joaof.eu>
Date: Sat, 17 Oct 2026 10:56:17 +0200
Subject: [PATCH] docs(agents): document version bumps, releases and the CI
 workflows

Add a "Bumping Versions" task: when a change to a published bundle needs a
bundle version bump, when both features need one, what needs none, and the
local command that runs the release version check through the features.
Update the CI/CD section, which still described verify.yml as running on
pushes to master: list the three workflows, merging through the merge
queue, and how releases work.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 AGENTS.md | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index c5e9d85c9..3527b5a8f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -139,8 +139,19 @@ These directories contain generated code - do not edit manually:
 xvfb-run ./mvnw verify -f ./ddk-parent/pom.xml -pl :com.avaloq.tools.ddk.xtext.test
 ```
 
+### Bumping Versions
+CI fails with "Only qualifier changed" when a published bundle or feature differs from the last release (`p2/releases/latest`) but keeps its version.
+1. Changing a published bundle (one included in the features, incl. `test.core`, `test.ui`, `xtext.test.core`): find the last release with `git tag --list 'v*' --merged HEAD --sort=-version:refname | head -1` and compare, `git show <tag>:<bundle>/META-INF/MANIFEST.MF`. Same version → bump the patch in `META-INF/MANIFEST.MF` (`x.y.z.qualifier`) and `pom.xml` (`x.y.z-SNAPSHOT`). Already higher → leave it.
+2. If both features still carry the last release's version, bump them to the next patch (e.g. 19.3.0 → 19.3.1) in `com.avaloq.tools.ddk.feature` and `com.avaloq.tools.ddk.runtime.feature` (`feature.xml`, `pom.xml`) and both entries in `ddk-repository/category.xml`.
+3. No bump for changes outside published bundles (`ddk-parent`, workflows, other `*.test` modules).
+4. Verify through the features:
+```bash
+./mvnw -f ./ddk-parent/pom.xml -pl :ddk-target,:com.avaloq.tools.ddk.runtime.feature,:com.avaloq.tools.ddk.feature,:ddk-repository -am -T 3C -DskipTests verify
+```
+
 ## CI/CD
 
 - **Platform**: GitHub Actions
-- **Workflow**: `.github/workflows/verify.yml`
-- Triggers on: push to master, pull requests
+- **Workflows**: `.github/workflows/verify.yml` (pull requests and the merge queue), `snapshot.yml` (pushes to `master`, publishes the p2 snapshot), `release.yml` (manual)
+- **Merging**: PRs merge through the merge queue on `master`.
+- **Releases**: run the `release` workflow (`version_bump`: patch/minor/major). It tags and republishes the head's snapshot, and fails unless every `feature.xml` already has the release version. For a minor/major release, first set both features and `category.xml` to it in a PR (e.g. "build: prepare DDK release 19.3.0").