diff --git a/docs/design_decisions/DR-005-infra.rst b/docs/design_decisions/DR-005-infra.rst new file mode 100644 index 00000000000..d259ab5347d --- /dev/null +++ b/docs/design_decisions/DR-005-infra.rst @@ -0,0 +1,212 @@ +.. + Copyright (c) 2026 Contributors to the Eclipse Foundation + + See the NOTICE file(s) distributed with this work for additional + information regarding copyright ownership. + + This program and the accompanying materials are made available under the + terms of the Apache License Version 2.0 which is available at + https://www.apache.org/licenses/LICENSE-2.0 + + SPDX-License-Identifier: Apache-2.0 + + +DR-005-Infra: Development, Release and Bugfix workflows +======================================================= + +.. dec_rec:: Development, Release and Bugfix workflows + :id: dec_rec__infra__dev_release_bugfix + :status: accepted + :context: Infrastructure + :decision: Polyrepo release process with manifest repository + + Date: 2026-01-08 + + +Context +------- + +This project consists of multiple independently developed modules stored in separate +repositories (polyrepo setup). + +This ADR builds on +`DR-002 (Integration Testing in a Distributed Monolith) <./DR-002-infra.md>`_, which +establishes: + +- the polyrepo structure, +- centralized responsibility for cross-repository integration, +- and infrastructure-owned integration tooling and processes. + +Within that context, this ADR defines **how coordinated product releases are produced** +from independently developed and versioned modules, while allowing continuous +integration to reduce the gap between development and release. + +Commonly referenced workflows do not fully address this problem space: + +- **Trunk-Based Development** with standard SemVer cannot represent parallel + release streams needed for supporting multiple product versions simultaneously. +- **Gitflow** adds branching complexity without solving the versioning problem + for parallel releases in a polyrepo setup. + +This ADR evaluates branching and versioning strategies explicitly designed for +**polyrepo systems with coordinated integration releases and continuous verification**. + + +Requirements and Goals +---------------------- + +Requirements +^^^^^^^^^^^^ + +Options that do not satisfy these requirements are not viable and will be rejected: + +- Reproducible and auditable release snapshots +- During working on a release, working on the main branch should still be possible +- Working on a release branch should be always possible and not harm the development on the main branch (resp. vice versa) +- Working on a bugfix should always be possible (for any old release) +- Module developers must know how to name their released versions +- The versioning scheme must clearly indicate which product release a module version + belongs to, enabling parallel release, which essentially means the ability to + maintain previous releases. +- Explicit stabilization phases +- Continuous integration before formal releases + +Optimization Goals +^^^^^^^^^^^^^^^^^^ + +Among viable options, we optimize for: + +- Independent module lifecycles without blocking development +- A process that scales across many repositories and teams +- Minimal integration governance to coordinate releases across repositories + + +Options Considered +------------------ + +Option 3.1: Trunk-Based Development +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Trunk-based development is a branching model where all developers work on a single main +branch ("trunk"), integrating changes frequently—ideally daily. Feature and bugfix +development happens directly on the trunk or in very short-lived branches that are +merged back quickly. Long-lived release branches and parallel release streams are +explicitly avoided. Releases are created directly from the trunk, and if a release +branch is needed for final stabilization or a hotfix, it is kept as short-lived +as possible. Bugfixes are made on the trunk and only cherry-picked to a release +branch in rare cases where a hotfix for an older release is required. Versioning +is linear, and the model does not support parallel maintenance of multiple +product versions. + +**Pros** + +- Very simple and lightweight branch structure. +- Maximizes integration and fast feedback through continuous integration. +- Minimizes merge conflicts and versioning issues. + +**Cons** + +- Parallel maintenance of multiple product versions (e.g., for long-term support) is + not feasible. +- Not suitable for polyrepo setups that require parallel support of several releases, + as parallel release streams are not supported by design. +- Requires explicit integration governance. + +.. note:: + The versioning and merge conflicts described in the diagram below typically + arise when deviating from strict trunk-based development and introducing long-lived + release branches. This is no longer considered state-of-the-art trunk-based development. + +.. mermaid:: + + gitGraph + commit id: "1.2.3" + + branch release + checkout release + commit id: "1.2.3-v1.0" + + checkout main + branch bugfix + checkout main + + commit + commit id: "1.2.4" + commit + commit id: "1.2.6" + + checkout bugfix + commit id: "bugfix-work" + + checkout release + merge bugfix + commit id: "1.2.5" + + checkout main + merge bugfix + + +Option 3.2: Gitflow Across Repositories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Uses the Gitflow branching model where modules maintain both ``main`` and ``develop`` +branches, with release branches created for stabilization. The manifest +repository (per DR-002) creates release branches (e.g., ``release/v1.0``), and each +participating module repository creates corresponding release branches. + +**Pros** + +- Well-known branching model. +- Explicit ``develop`` branch separates ongoing work from release stabilization. +- Release branches provide clear stabilization phases. + +**Cons** + +- Parallel maintenance of multiple product versions (e.g., for long-term support) is + not feasible. +- Standard SemVer suffers from the same parallel release stream problem as Option 3.1 (version numbering conflicts). +- Additional overhead of maintaining separate ``develop`` branches across all repositories. +- More complex branching model increases coordination complexity in a polyrepo setup. +- Does not scale well with increasing module count. +- Requires explicit integration governance. + + +Option 3.3: Polyrepo Release Process with Manifest Repository and relaxed version of SemVer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As described in +`DR-002 (Integration Testing in a Distributed Monolith) <./DR-002-infra.md>`_ there is +a dedicated manifest repository containing the "known goods sets". There is a known +good set for the latest version, but also known good sets for released versions. +The known good set specifies the exact version of each module. Additionally, we store +the hash to ensure the integrity of the version. + +Bugfixes for previous releases are handled by checking out the corresponding commits +in the manifest and the affected modules, applying the fix, and updating the +manifest to reference the new module version. + +**Pros** + +- Single source of truth for product integration. +- Supports continuous verification. +- Provides reproducible releases. +- Scales with module count and team autonomy. +- Clear separation between development, integration, and stabilization. + +**Cons** + +- Requires explicit integration governance. + + +Decision +-------- + +We decided for **Option 3.3**. + +Rationale +^^^^^^^^^ + +Options 3.1 and 3.2 are not feasable for parallel maintenance of multiple product +versions. + +Option 3.3 is the only viable option as it satisfies all requirements.