DR-005: Release strategy #2400

olivembo · 2026-01-12T07:25:09Z

Establish a polyrepo release process with a manifest repository and relaxed SemVer for coordinated product releases.

…ction

a-zw · 2026-01-12T07:47:42Z

docs/design_decisions/DR-005-infra.md

+
+### 3.1 Trunk-Based Development with SemVer
+
+Assumes continuous deployment on a longlived branch, e.g. `main` and does not define coordinated product releases.


This describes "trunk-based" with "does not define coordinated product releases". This implies that either

This is not valid option as it does not achieve the goals. It should not even be considered but removed from this decision record.

This option needs to describe how coordinate product releases given trunk-based development. The description must be extended accordingly.

I will adapt the document according to 2.

a-zw · 2026-01-12T07:50:33Z

docs/design_decisions/DR-005-infra.md

+
+### 3.2 Gitflow Across Repositories
+
+Introduces coordinated release branching across repositories but lacks a central integration manifest.


How does "coordinated release branching across repositories" work? This option is not described sufficiently.

Will describe in further detail

a-zw · 2026-01-12T07:54:52Z

docs/design_decisions/DR-005-infra.md

+- 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
+- It must be clear how to do the integration, means what to reference (e.g. „extended“ semver as 1.2.3-etas-r1.0)


Option 3.3 lists "integration governance" as a Con. However, some people would consider that lack of a such governance as undesirable lack of control.

Add "minimal integration governance" as a goal to document our assumption that we want that.

Will add this point to the goals section

docs/design_decisions/DR-005-infra.md

a-zw · 2026-01-12T07:59:40Z

docs/design_decisions/DR-005-infra.md

+
+## 4. Decision
+
+We decided for **Option 3.3**.


As of now this decision record is pointless. It puts up two strawmen options (3.1 and 3.2) and dismisses them for not achieving the goals. If there is only a single valid option, then there is no decision to be made.

a-zw · 2026-01-12T08:02:43Z

docs/design_decisions/DR-005-infra.md

+
+---
+
+## 2. Goals and Requirements


Can we distinguish between requirements (which must be satisfied) and optimization goals (where we try to find the best option)?

There is no point in invest time looking into option which don't satisfy requirements. Also, goals are usually few and that simplifies the decision evaluation.

This would be helpful. The amount of strict requirements are probably much lower than the goals.

Co-authored-by: Andreas Zwinkau <95761648+a-zw@users.noreply.github.com> Signed-off-by: Oliver Emrich <oliver.emrich2@bosch.com>

github-actions · 2026-01-12T08:26:11Z

The created documentation from the pull request is available at: docu-html

opajonk · 2026-01-12T08:33:38Z

docs/design_decisions/DR-005-infra.md

+- Continuous integration before formal releases
+- Independent module lifecycles without blocking development
+- A process that scales across many repositories and teams
+- Working on the main branch should be always possible


What does "working on the main branch" mean here? I understand the main branch like this: "latest and greatest, always in a working state". That means you cannot actually "work on" the main branch: you must always branch off, then work, make sure the work is "fully done", integrate.

I would also use e.g. "codeline" instead of "branch", and define codeline as "The set of branches of the same name across all S-CORE repositories.". If useful, one can go more into details and write "Each of the branches of a codeline must have been created from the same head branch, in a state consistent with a head codeline."

The point is that module devs should be able to push new features on their module main branch while the integration is still busy integrating an older version. No announcements like "only merge bugfixes until the 0.5 release final is done".

In other words, it implies that modules must have some kind of release branches for hotfixes.

OK so the "normal codefreeze concept", right?

"On the 31st January, 15:00 we will cut the release branches for 1.0.0" --> on all modules, of course. Release branch creation takes a minute, and just after that everyone can continue to work on the mainline.

opajonk · 2026-01-12T08:33:41Z

docs/design_decisions/DR-005-infra.md

+
+---
+
+## 2. Goals and Requirements


This would be helpful. The amount of strict requirements are probably much lower than the goals.

opajonk · 2026-01-12T08:39:03Z

docs/design_decisions/DR-005-infra.md

+    commit id: "1.2.3-r1.0"
+
+    checkout main
+    branch bugfix


I think this is likely not correct. You need to create a support branch for 1.2.x, which starts at 1.2.0, where you can create 1.2.1, 1.2.2, 1.2.3, 1. 1.2.4 etc. from. These cannot come from a main line, where development for 1.3.x (or even 2.x.x) continues. The patch releases are by defintion only bugfix releases and cannot contain new features.

(This assumes that on main you continue with new features, i.e. minor updates in the sense of SemVer)

I think GitFlow actually does a good job to capture all of this (main, release, support, bugix, how to connect branches to SemVer).

The problems with SemVer are described here: https://beza1e1.tuxen.de/patching_old_versions.html

Do you agree with the limitations described in there?

Yes, sure - but that description is purely about "What to do if you need to do a breaking change to an old version?" - so strictly about major versions.

Why would you do a breaking change to an already released major version? You can fix bugs, you can add compatible features, but breaking change simply means: new major version. And you cannot break an existing major release. I think we've picked the development model that is described below "Instead I want to hint at a solution on a higher level." in the text?

(Just to be clear: I do not see SemVer religiously as the secret sauce that solves everything 😄 - for example, when distributions come into play and distributors are patching / backporting / ... it stops working and gets really messy. Cf. the "versioning scheme" of Debian, which is more or less a collection of necessities created over years of experience...

However, S-CORE is (here, during regular development at least!) not a distribution, right?)

opajonk · 2026-01-12T08:42:46Z

docs/design_decisions/DR-005-infra.md

+- Provides release branches for stabilization.
+
+**Cons**:
+- Requires coordination of release branches across all repositories.


I don't get this point: the branching model simply deals with a single repository. If you want to enhance it for a multi-repo, you have to do something in addition. I do not see this as a drawback really... a branching model alone can never do this. You need something like the reference_integration, with its lockfile method (this json file we create is nothing else).

opajonk · 2026-01-12T08:43:15Z

docs/design_decisions/DR-005-infra.md

+**Cons**:
+- Requires coordination of release branches across all repositories.
+- Lacks a single source of truth for integration state.
+- Does not scale well with increasing module count.


Again, this is comparing apples and oranges...

opajonk · 2026-01-12T08:44:22Z

docs/design_decisions/DR-005-infra.md

+    merge bugfix
+```
+> *Explaination:* Using SemVer quickly reaches its limits.
+If branching off from a version e.g. 1.2.3 and needing a bugfix while the development on main goes on where other versions e.g. 1.2.4 are created, now on a release branch you would need to use the version 1.2.5. The development on main for the next version needs to use 1.2.6 although the logical predecessor is 1.2.4. This violates SemVer since backward compatibility in that case is (or could be) broken.


As stated above I think this is not correct. SemVer has no issues with this, but the connection to the branching model must be done correctly.

opajonk · 2026-01-12T08:47:16Z

docs/design_decisions/DR-005-infra.md

+
+### 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 release(d) versions. Because of the earlier described limitations of SemVer, the correct module versions should not be referenced in the `MODULE.bazel` (in the manifest repository) as e.g., `1.2.3` but either by referencing the git commit hash directly or using a relaxed SemVer string, e.g. as `1.2.3-v1.0` where the string after the hyphen represents the respective S-CORE release.


I do not agree here. We can simply cut a release branch of all modules, which "captures" a minor version of the module (i.e. all 1.1.x versions). The versions 1.1.0, 1.1.1 etc are the "line of module versions agreed for a specific S-CORE release". S-CORE-bugfix releases then take bugfix releases of the modules. etc.

opajonk · 2026-01-12T08:48:35Z

docs/design_decisions/DR-005-infra.md

+
+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 release(d) versions. Because of the earlier described limitations of SemVer, the correct module versions should not be referenced in the `MODULE.bazel` (in the manifest repository) as e.g., `1.2.3` but either by referencing the git commit hash directly or using a relaxed SemVer string, e.g. as `1.2.3-v1.0` where the string after the hyphen represents the respective S-CORE release.
+
+With that approach releases are possible, e.g. by creating a release branch in the integration repository as well as in the affected module repositories. Also bugfixes of "old" releases are possible by checking out the repective release branch in the reference integration and if necessary to also created bugfixes in the affected modules.


This is correct, but as outlined above it does not really require a "modified SemVer". The standard one would do :-)

opajonk · 2026-01-12T08:50:46Z

docs/design_decisions/DR-005-infra.md

+**Rationale**
+
+This approach reflects established industry practice for large-scale polyrepo systems using
+manifest-based integration and release trains (e.g. Android/AOSP, Chromium-style roll-ups),


In the end I agree with the conclusion: we need a manifest / lock file / call-it-what-you-want. But we do not need special branching methods or a new mapping to SemVer. The standard stuff does the job, when thinking about "codelines" (= sets of branches with same name/purpose) instead of "single-repository-branches".

opajonk · 2026-01-12T08:52:25Z

docs/design_decisions/DR-005-infra.md

+
+Option 3.1 (Trunk-Based Development Only) has been rejected because it does not address the need for coordinated product releases or explicit stabilization phases in a poly repo environment.
+
+Option 3.2 (Gitflow Across Repositories) has been rejected because it requires coordinating release branches across all repositories and lacks a central integration manifest, which does not scale well.


With this I am a bit confused: of course we will need coordinated release branches across all repositories - simply for consistency reasons during stabilization. There is no way that a module introduces new features into a release when stabilization is already happening.

However, release branch cutting (i.e. "code freeze") is trivially scriptable, and a matter of 3 minutes across all repositories - given that you use a workspace like available via gitea on reference-integration. All you have to do is to announce "code freeze day & time" and fire the script. This is absolutely no problem if your mainline is always stable and integrates well. And this we have already outlined in DR-002.

arsibo · 2026-01-13T07:40:22Z

Please rename to DR-006. I use DR-005 #2346

guejan · 2026-01-13T13:28:52Z

docs/design_decisions/DR-005-infra.md

+
+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 release(d) versions. Because of the earlier described limitations of SemVer, the correct module versions should not be referenced in the `MODULE.bazel` (in the manifest repository) as e.g., `1.2.3` but either by referencing the git commit hash directly or using a relaxed SemVer string, e.g. as `1.2.3-v1.0` where the string after the hyphen represents the respective S-CORE release.
+
+With that approach releases are possible, e.g. by creating a release branch in the integration repository as well as in the affected module repositories. Also bugfixes of "old" releases are possible by checking out the repective release branch in the reference integration and if necessary to also created bugfixes in the affected modules.


Suggested change

With that approach releases are possible, e.g. by creating a release branch in the integration repository as well as in the affected module repositories. Also bugfixes of "old" releases are possible by checking out the repective release branch in the reference integration and if necessary to also created bugfixes in the affected modules.

With that approach releases are possible, e.g. by creating a release branch in the integration repository as well as in the affected module repositories. Also bugfixes of "old" releases are possible by checking out the respective release branch in the reference integration and if necessary to also created bugfixes in the affected modules.

guejan · 2026-01-13T13:29:32Z

docs/design_decisions/DR-005-infra.md

+- Clear separation between development, integration, and stabilization.
+
+**Cons**:
+<<<<<<< HEAD


Suggested change

<<<<<<< HEAD

Unresolved merge conflict.

olivembo added 5 commits January 8, 2026 14:43

Added initial version of DR-005-infra.md

96e738c

Added chapter numbers

38f2a00

Shortened semver chapter

a5f3aff

Moved out of scope section and removed "Consequences & Challenges" se…

77dc654

…ction

Incorporated review comments and shrinked down the document

e4adfa9

olivembo requested review from AlexanderLanin and dcalavrezo-qorix as code owners January 12, 2026 07:25

a-zw suggested changes Jan 12, 2026

View reviewed changes

olivembo and others added 2 commits January 12, 2026 09:21

Update docs/design_decisions/DR-005-infra.md

7b5a2a6

Co-authored-by: Andreas Zwinkau <95761648+a-zw@users.noreply.github.com> Signed-off-by: Oliver Emrich <oliver.emrich2@bosch.com>

Update docs/design_decisions/DR-005-infra.md

0c4eb9c

Co-authored-by: Andreas Zwinkau <95761648+a-zw@users.noreply.github.com> Signed-off-by: Oliver Emrich <oliver.emrich2@bosch.com>

olivembo added 3 commits January 12, 2026 09:47

Adressed eclipse-score#2400 (comment)

22a63b6

Addresses review comment eclipse-score#2400 (comment)

0529659

Addresses review comment eclipse-score#2400 (comment)

7e32534

opajonk suggested changes Jan 12, 2026

View reviewed changes

olivembo added 3 commits January 12, 2026 10:00

Restructured chatper 2

d1d9e74

Minor changes

08ea69a

Minor changes

2b6cf6a

guejan reviewed Jan 13, 2026

View reviewed changes

Fixed typos and inconsistencies

bb3deae

olivembo marked this pull request as draft January 13, 2026 16:10

olivembo added 2 commits January 13, 2026 17:12

Reworked chapter 3.1

dd67caa

Reworked some chapters and fixed grammar

efec293


		### 3.1 Trunk-Based Development with SemVer

		Assumes continuous deployment on a longlived branch, e.g. `main` and does not define coordinated product releases.


		### 3.2 Gitflow Across Repositories

		Introduces coordinated release branching across repositories but lacks a central integration manifest.


		### 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 release(d) versions. Because of the earlier described limitations of SemVer, the correct module versions should not be referenced in the `MODULE.bazel` (in the manifest repository) as e.g., `1.2.3` but either by referencing the git commit hash directly or using a relaxed SemVer string, e.g. as `1.2.3-v1.0` where the string after the hyphen represents the respective S-CORE release.


		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 release(d) versions. Because of the earlier described limitations of SemVer, the correct module versions should not be referenced in the `MODULE.bazel` (in the manifest repository) as e.g., `1.2.3` but either by referencing the git commit hash directly or using a relaxed SemVer string, e.g. as `1.2.3-v1.0` where the string after the hyphen represents the respective S-CORE release.

		With that approach releases are possible, e.g. by creating a release branch in the integration repository as well as in the affected module repositories. Also bugfixes of "old" releases are possible by checking out the repective release branch in the reference integration and if necessary to also created bugfixes in the affected modules.


		Option 3.1 (Trunk-Based Development Only) has been rejected because it does not address the need for coordinated product releases or explicit stabilization phases in a poly repo environment.

		Option 3.2 (Gitflow Across Repositories) has been rejected because it requires coordinating release branches across all repositories and lacks a central integration manifest, which does not scale well.

DR-005: Release strategy #2400

Are you sure you want to change the base?

DR-005: Release strategy #2400

Conversation

olivembo commented Jan 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

opajonk Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

opajonk Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

arsibo commented Jan 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

opajonk Jan 13, 2026 •

edited

Loading

opajonk Jan 12, 2026 •

edited

Loading