From 83e1069851d5ef258929355132cc75dd14ff8627 Mon Sep 17 00:00:00 2001 From: DemchaAV Date: Mon, 6 Jul 2026 13:39:05 +0100 Subject: [PATCH] docs(contributing): document the 2.0 module-train versioning and 1.x branch model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Capture two policies for the 2.0 line: - Lockstep versioning (the "module train"): all published graph-compose* modules share one version and move together — a fix bumps the whole train by a patch, a feature by a minor; fonts/emoji keep their independent lines. release-process.md gains a 2.F section; the module-migration guide states the one-version rule up front. - Branch model: 2.0 work lives on 2.0-dev until GA; at GA main becomes the stable 2.0 line, develop the 2.x working branch, and a 1.x maintenance branch is cut from the final 1.9.x commit for critical / security fixes only (released as 1.9.x). --- CONTRIBUTING.md | 13 +++++++++++++ docs/contributing/release-process.md | 26 ++++++++++++++++++++++++++ docs/migration/v2.0.0-modules.md | 5 +++++ 3 files changed, 44 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96d3b210..a69a5a9c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,6 +83,19 @@ GraphCompose follows a fork → feature branch → pull request flow. Exte See [docs/contributing/release-process.md](./docs/contributing/release-process.md) for the full checklist (audit gates, hotfix protocol, lessons learned). +### Version lines and the 1.x maintenance branch + +GraphCompose is mid-transition to the 2.0 module line. Until 2.0 ships: + +- **`2.0-dev`** is the working branch for 2.0 — feature branches for 2.0 work target `2.0-dev`, not `develop`. +- **`develop`** and **`main`** carry the shipping **1.9.x** line; `main` is its stable, tagged surface (latest `v1.9.x`). + +At the **2.0 GA** merge the branches take their long-term roles: + +- **`main`** fast-forwards to 2.0 and becomes the stable 2.0 line. +- **`develop`** becomes the ongoing 2.x working branch (what `2.0-dev` was); `2.0-dev` retires. +- A **`1.x`** maintenance branch is cut from the final 1.9.x commit on `main` at that moment. It receives **critical fixes and security / CVE backports only — no features** — released as `1.9.x` patches from `1.x` via the same `cut-release.ps1` + tag flow. New feature work always targets the 2.x line. + ## Repository map - `src/main/java/com/demcha/compose/document/api`, `document.dsl`, `document.node`, `document.style`, `document.table`, `document.image`, `document.output`, `document.exceptions`, `document.snapshot` diff --git a/docs/contributing/release-process.md b/docs/contributing/release-process.md index f7beb7dd..cc8afcfa 100644 --- a/docs/contributing/release-process.md +++ b/docs/contributing/release-process.md @@ -161,6 +161,32 @@ fonts, so cutting an emoji release needs the same consumer re-pin. - **First publish:** `emoji/pom.xml` is already `1.0.0`; tag `emoji-v1.0.0` (on a commit that includes `publish-emoji.yml`) to ship it. +### 2.F The 2.0 module train (lockstep versioning) + +From 2.0 the library ships as several modules that move together as one **version +train**: `graph-compose-core`, the `graph-compose` compat wrapper, +`graph-compose-render-pdf` / `-render-docx` / `-render-pptx`, +`graph-compose-templates`, `graph-compose-testing`, and the `graph-compose-bundle` +aggregate. They all carry the **same** version. + +- **User rule (one sentence):** the same version across these modules is a + tested-compatible set — pin one version, use it for every `graph-compose*` module + you depend on, and upgrade them together. +- **What bumps when:** a fix in *any* train module bumps the **whole train** by a + patch; a feature bumps it by a minor. There is no per-module version drift within + the train. `cut-release.ps1` Step 1 bumps every train pom (`pom.xml`, `render-pdf`, + `render-docx`, `render-pptx`, `templates`, `testing`, `wrapper`, `bundle`) plus + `aggregator` / `examples` / `benchmarks` to the same `` in one pass; each + module's `graph-compose-core` dependency is `${project.version}`, so it follows + automatically, and `VersionConsistencyGuardTest` enforces the agreement. +- **Not in the train:** `graph-compose-fonts` and `graph-compose-emoji` keep their + own version lines and are pinned explicitly (§2.D / §2.E). They are the only + published artifacts that do *not* move with the engine version. +- **Beta / pre-release tags:** a hyphenated train tag (e.g. `v2.0.0-beta.1`) publishes + the whole train to the **GitHub Release pre-release surface only** — `publish.yml` + skips Central for hyphenated tags (§2.B step 9). A beta is therefore installable from + the GitHub pre-release (and from JitPack, which builds any tag), not from Central. + --- ## 2.C One-time Maven Central setup (maintainer) diff --git a/docs/migration/v2.0.0-modules.md b/docs/migration/v2.0.0-modules.md index 79b8a773..d92f728c 100644 --- a/docs/migration/v2.0.0-modules.md +++ b/docs/migration/v2.0.0-modules.md @@ -12,6 +12,11 @@ of the changelog](../../CHANGELOG.md); the rationale is [ADR 0016](../adr/0016-m `graph-compose-core` + `graph-compose-render-pdf`, so a 1.x caller who bumps the version keeps rendering PDF with **no code and no dependency change**. +**One version for everything.** All `graph-compose*` modules share a single version — +pin one version and use it for every module you depend on, and upgrade them together. +(The independently-versioned `graph-compose-fonts` and `graph-compose-emoji` add-ons are +the only exceptions; see [Which artifact now?](#which-artifact-now).) + ```xml io.github.demchaav