Clearify Development/Release Process

[mjacoby]

Follow-up ticket from admin-shell-io/java-serializer#61

We need to clarify how the development & release process works, w.r.t. branch-naming, tagging, and release.
Previously (under admin-shell.io), a push on main branch triggered a maven release. Current pipeline seems to trigger a maven release when a Github release is made.
I propose changing the pipeline to trigger upon creating of a tag following the format vX.Y.Z and don't release on Github at all (maybe SNAPSHOTs but they can also be released via maven).

We should also define additional things like

• How to do hot fixes, i.e. fixes an older released versions (e.g. create branch before creating a release tag and keep that branch)
• How to keep dependencies up-to-date (only for latest version or also older versions?)

[twebermartins]

Valid point! We should look for best practices in the open source community but also keeping the Eclipse Handbook in mind. In particular, we need to be careful to not publish / release anything that has not been through the official review.

Just to keep in mind, we would have the following releases requiring release review:

• Major releases include API changes (potential for downstream breakage);
• Minor releases add new functionality, but are API compatible with previous versions; and
• Service releases include bug fixes only and include no significant new functionality.

There is also Milestone builds and release candidates that are not official releases and thus they do not require to go through the review process.

So, I think we should select the branch naming and the development / release process accordingly.
Regarding branches and development / release process, there are some interesting articles discussing this like Patterns for Managing Source Code Branches from Martin Fowler or Gitkraken.

I will have a look how other projects do this.

[twebermartins]

Here are some ideas that we can discuss.

Aft we have an agreement, we should add these processes into the decision records.

[mjacoby]

I have a few questions/remarks regarding the proposed development process

1. change master to main
2. What is the need of having a separate develop branch? From my perspective there is not much advantage keeping latest features from main. In contrary, merging finished but unreleased features to main makes it easier for people to try out even before them being released.
3. Create release branches not for every release but only per minor version, e.g. release-v1.1.x. Each release should be created as a tag.
4. Branch housekeeping: Only permanent branches are main, develop, release-v0.0.x; other branches are deleted once merged.
5. How about alternative branch names besides feature, e.g. bugfix (as bugfixes != hotfixes)? I the previous projects I also regularly used something like refactoring for structural changes, e.g. improving code quality but also like update the CI pipeline etc.

[twebermartins]

Thanks @mjacoby

To your points:

1. change master to main: definitely! I just leveraged the picture as an example, but the description uses main instead of master
2. What is the need of having a separate develop branch? From my perspective there is not much advantage keeping latest features from main. In contrary, merging finished but unreleased features to main makes it easier for people to try out even before them being released.: I would be open for that as long all others agree on that too
3. Create release branches not for every release but only per minor version, e.g. release-v1.1.x. Each release should be created as a tag.: agree, we should integrate this point into the guidelines
4. Branch housekeeping: Only permanent branches are main, develop, release-v0.0.x; other branches are deleted once merged.: agreed, let's integrate this one too
5. How about alternative branch names besides feature, e.g. bugfix (as bugfixes != hotfixes)? I the previous projects I also regularly used something like refactoring for structural changes, e.g. improving code quality but also like update the CI pipeline etc.: I am good with you proposal

[twebermartins]

Can we create an "example" (use case) based on our needs to understand what we need?

[twebermartins]

look:
https://github.com/eclipse/rdf4j/blob/main/CONTRIBUTING.md

https://github.com/eclipse/milo

[twebermartins]

11-10-22 Decisions:

• We don't need a development branch, we use main to maintain the last development status
• Branch name should always have a tag (release, bugfix, …)

Still open:

• Release branch only for a major version (should be aligned with latest spec of AAS)?

[twebermartins]

Closing issue as we agreed on this process. Please reopen the issue in case it does not applies.