Release Lifecycle

Managing a release that touches more than one repository requires deliberate ordering: the wrong merge sequence can break CI, introduce broken version references, or accidentally ship local development overrides. This guide covers the conventions for CHANGELOG management, PR creation, merge ordering, version catalog updates, and composite build safety.

For the mechanics of wiring up a local composite build during development, see multi-repo-development.md.

When This Guide Applies

Follow these conventions whenever:

A change modifies source code in two or more repositories that have a dependency relationship.
A project plan includes CHANGELOG updates, PRs, or version catalog changes.
You are using parallel git worktrees to implement changes across a repository.

CHANGELOG Management

Format

Each repository maintains a CHANGELOG.md at its root following Keep a Changelog conventions. The unreleased section always sits at the top:

## [Unreleased]

### Added
- <new feature description> (DQ-NNN if a design decision drove it)

### Changed
- <modification description>

### Fixed
- <bug fix description>

Group entries under one of: Added, Changed, Fixed, Deprecated, Removed, or Security.

Rules

Every task that modifies source code must produce a CHANGELOG entry in the same PR.
Reference decision log entries (DQ-NNN) for design-level changes.
CHANGELOG updates are a separate tracked task in the project plan — they are not bundled silently inside implementation tasks.

Category Selection and Version Impact

Each CHANGELOG category maps to a Semantic Versioning increment via the repository’s changemap.json. Be deliberate about category choice — it directly determines the version bump:

Changed and Removed trigger a major version bump.
Added and Deprecated trigger a minor version bump.
Fixed and Security trigger a patch version bump.

When a PR includes both new features and refactoring of existing APIs, prefer expressing the refactoring under Fixed (if it corrects a bug or improves behavior) or as part of the Added narrative (if the refactoring is a prerequisite for the new feature) rather than using Changed. Reserve Changed for intentional, standalone breaking changes to existing functionality. A factory signature change that is a side effect of adding new capabilities does not necessarily warrant a Changed entry if it can be accurately described under Added or Fixed.

PR Naming

Follow the conventional commit format: <type>: <short description>, where type is one of feat, fix, refactor, test, docs, or chore.

PR Creation and Merge Ordering

Dependency-Ordered Merging

For repositories with dependency chains, PRs must be created and merged in reverse dependency order — upstream first. The downstream PR should not be merged until the upstream version is published and available.

A typical chain for Arda backend components looks like:

common-module PR  -->  merge  -->  tag
        |
        v
operations PR (update version catalog)  -->  merge  -->  tag
        |
        v
api-test PR  -->  merge  -->  tag

Per-Repository PR Lifecycle

Each repository follows this sequence as distinct tasks in the project plan:

Step	Task	Description
1	Update CHANGELOG	Add entries under `[Unreleased]`
2	Version catalog update	Update `gradle/libs.versions.toml` if consuming upstream changes
3	Revert local overrides	Remove `includeBuild("../...")` or composite build paths
4	Final build and test	`make build` to verify with published (not local) dependencies
5	Create PR	Target the base branch (typically `main`; confirm before creating)
6	Code review	Automated and/or manual review
7	Merge PR	Merge after review approval
8	Tag release	Tag the merged commit if versioning applies

Step 3 — reverting local overrides — is critical. See Composite Build Safety below.

Cross-Repository PR Dependencies

When the downstream PR cannot be merged before the upstream, communicate this clearly in the PR description:

> [!IMPORTANT]
> This PR depends on [`common-module` #<pull-request-number>](https://github.com/Arda-cards/common-module/pull/<pull-request-number>).
> Please review and merge it first.

Integration Branch Pattern (Multi-Worktree Projects)

When a project uses parallel git worktrees all writing to the same repository, use an integration branch to consolidate changes before opening a PR to the base branch. This gives reviewers a single unified diff and avoids partial-state merges.

Identify the base branch before any work begins. The base branch is the branch the PR will ultimately target (typically main, but could be dev, stage, or a pre-existing feature branch). The base branch is never modified locally.
Create an integration branch from the base branch:
```
<username>/<project-name>-integration
```
Each worktree branch is merged into the integration branch (not the base branch) when its tasks complete.
Open one PR from the integration branch to the base branch. This is the only PR for the project in that repository.
Clean up after the PR merges: delete the integration branch and remove the worktrees (see Worktree Cleanup).

Version Catalog Updates

When an upstream repository publishes a new version:

Update gradle/libs.versions.toml in the downstream repository.
Run make build to verify the downstream project compiles and all tests pass against the newly published version.
Include the version catalog update in the downstream PR.

Example libs.versions.toml entry:

arda-common-version = "2.1.0"
arda-common = { module = "cards.arda.common:lib", version.ref = "arda-common-version" }

Composite Build Safety

Local Development with `includeBuild`

During development, Gradle composite builds (includeBuild("../common-module")) allow you to iterate locally without publishing. See multi-repo-development.md for how to configure this.

Worktree Path Awareness

When working in a git worktree, the relative path ../common-module resolves differently than it does from the main checkout. Use an existence check so the includeBuild only activates when the path actually resolves:

// settings.gradle.kts — worktree-aware override
val commonModulePath = file("../common-module")
if (commonModulePath.exists()) {
    includeBuild(commonModulePath)
}

Push Guards

Never push composite build overrides to the remote. Three safeguards prevent this:

Pre-commit check: Before committing, verify that settings.gradle.kts does not contain includeBuild("../...") referencing local sibling paths.
Explicit plan task: Every project plan that uses composite builds must include a “Revert composite build paths” task, sequenced before PR creation.
Code review: Reviewers must flag any includeBuild referencing local (../*) paths.

Worktree Cleanup

After all branches are merged and the project is complete:

# Confirm which worktrees belong to this project
git worktree list

# Remove each project worktree
git worktree remove <workspace-root>/${projectName}-worktrees/${taskName}

# Remove the now-empty parent directory
rmdir <workspace-root>/${projectName}-worktrees

# Prune stale worktree references
git worktree prune

Before removing a worktree, verify:

All branches have been merged or pushed to the remote.
There are no uncommitted changes (git -C <worktree-path> status).
The worktree lives under the ${projectName}-worktrees/ parent directory.

If a worktree has uncommitted changes, do not remove it until the changes are resolved.

Cross-Repository Development Checklist

Address these questions early in any multi-repo project plan:

#	Question	Purpose
1	What is the repository dependency chain?	Determines merge order
2	How does local development resolve cross-repo dependencies?	Identifies composite build or symlink needs
3	Will worktrees be used? If so, do composite build paths need adjustment?	Prevents path resolution failures
4	What version catalog entries need updating?	Tracks downstream version bumps
5	Are there CI/CD pipelines that need to pass between merges?	Identifies pipeline gates

multi-repo-development.md — How to configure local composite builds and the options for structuring cross-repo changes during development.
running-api-tests.md — Running the API test suite after deploying a newly built component.
working-with-agents.md — If an agent team is executing the release, the launch-team workflow and integration branch strategy described there align with this guide.
Arda workspace repository — Project plans, decision logs (DQ-NNN references), and the canonical version catalog for active projects.