docs: add release and dev process

eclipse-tractusx · Oct 14, 2024 · 46e0c4a · 46e0c4a
1 parent b924bf8
commit 46e0c4a
Show file tree

Hide file tree

Showing 3 changed files with 172 additions and 0 deletions.
diff --git a/docs/technical documentation/14. How to contribute.md b/docs/technical documentation/14. How to contribute.md
@@ -96,6 +96,10 @@ The suggested naming convention is '{type}{(function)}: {short summary}'
 Add details to the change, fix or feature in the PR description.
 What was changed, why was it changed (e.g. which issue was fixed or which requirement was implemented), and how was it changed.
 
+### Additional information
+
+Please refer to the [Development Flow](./17.%20Dev%20Flow.md).
+
 ## NOTICE
 
 This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).

diff --git a/docs/technical documentation/17. Dev Flow.md b/docs/technical documentation/17. Dev Flow.md
@@ -0,0 +1,69 @@
+# Dev flow (git diagram)
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+gitGraph
+    commit id: "chore: initial commit"
+    branch feature/feature1 order: 1
+    checkout feature/feature1
+    commit id:"feat(function): add feature1"
+    checkout main
+    merge feature/feature1
+    branch feature/feature2 order: 3
+    checkout feature/feature2
+    commit id:"feat(function)!: WIP enable feature2"
+    checkout main
+    branch bug/bug1 order: 2
+    commit id: "fix(function): change bug1"
+    checkout main
+    merge bug/bug1
+    checkout feature/feature2
+    commit id:"feat(function)!: finalize feature2"
+    checkout main
+    merge feature/feature2
+    branch feature/feature3 order: 4
+    commit id:"feat(function)!: WIP enable feature3"
+    checkout main
+    branch release/v1.0.0-rc.1 order: 5
+    commit id: "build(v1.0.0-rc.1): bump version" tag: "v1.0.0-rc.1"
+    checkout main
+    merge release/v1.0.0-rc.1
+    checkout release/v1.0.0-rc.1
+    branch bug/bug2 order: 7
+    checkout bug/bug2
+    commit id: "fix(function): change bug2"
+    checkout release/v1.0.0-rc.1
+    branch release/v1.0.0-rc.2 order: 8
+    checkout release/v1.0.0-rc.2
+    merge bug/bug2
+    commit id: "build(v1.0.0-rc.2): bump version" tag: "v1.0.0-rc.2"
+    checkout main
+    merge release/v1.0.0-rc.2
+    checkout feature/feature3
+    commit id:"feat(function)!: finalize feature3"
+    checkout main
+    merge feature/feature3
+    checkout release/v1.0.0-rc.2
+    branch release/v1.0.0 order: 8
+    checkout release/v1.0.0
+    commit id: "build(v1.0.0): bump version" tag: "v1.0.0"
+    checkout main
+    merge release/v1.0.0
+    checkout release/v1.0.0
+    branch hotfix/v1.0.1 order: 9
+    checkout hotfix/v1.0.1
+    branch bug/bug3 order: 10
+    checkout bug/bug3
+    commit id: "fix(function): change bug3"
+    checkout hotfix/v1.0.1
+    merge bug/bug3
+    commit id: "build(v1.0.1): bump version" tag: "v1.0.1"
+```
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-iam
diff --git a/docs/technical documentation/18. Release Process.md b/docs/technical documentation/18. Release Process.md
@@ -0,0 +1,99 @@
+# Release Process
+
+The release process for a new version can roughly be divided into the following steps:
+
+- [Release Process](#release-process)
+  - [Preparations on the release branch](#preparations-on-the-release-branch)
+    - [1. Version bump](#1-version-bump)
+    - [2. Update README (on chart level)](#2-update-readme-on-chart-level)
+  - [Update CHANGELOG.md](#update-changelogmd)
+  - [Merge release branch](#merge-release-branch)
+  - [RC: provide successive rc branch and change base of open PRs](#rc-provide-successive-rc-branch-and-change-base-of-open-prs)
+  - [NOTICE](#notice)
+
+The process builds on the [Development Flow](./17.%20Dev%20Flow.md) which, usually, takes place within forks and leads to merged pull requests in the repositories of the eclipse-tractusx organization.
+
+For assigning and incrementing **version** numbers [Semantic Versioning](https://semver.org) is followed.
+
+## Preparations on the release branch
+
+Checking out from the main branch a release branch (release/{to be released version} e.g. release/v1.2.0, or respectively release/v1.2.0-rc.1 for a release candidate).
+On the release branch the following steps are executed:
+
+### 1. Version bump
+
+Bump the chart and app version in the `Chart.yaml` files.
+
+- [centralidp/Chart.yaml](../../charts/centralidp/Chart.yaml)
+- [sharedidp/Chart.yaml](../../charts/sharedidp/Chart.yaml)
+
+And bump the version of the images for the init container and realm seeding job in the `values.yaml` files:
+
+- [centralidp/values.yaml](../../charts/centralidp/values.yaml)
+- [sharedidp/values.yaml](../../charts/sharedidp/values.yaml)
+
+_environment relevant: Update the version of the targetRevision tag in the [argocd-app-templates](../../environments/argocd-app-templates/), used for hosted environments._
+
+Example for commit message:
+
+_build: bump version for vx.x.x_
+
+### 2. Update README (on chart level)
+
+Use [helm-docs](https://github.com/norwoodj/helm-docs) (gotemplate driven) for updating the README file.
+
+```bash
+helm-docs --chart-search-root [charts-dir] --sort-values-order file
+```
+
+Example for commit message:
+
+_build: update readme for vx.x.x_
+
+## Update CHANGELOG.md
+
+The changelog file tracks all notable changes since the last released version.
+Once a new version is ready to be released, the changelog can get updated via an automatically created pull request using the [release-please workflow](../../../.github/workflows/release-please.yml) which can be triggered manually or by pushing a _changelog/v*.*.*_ branch.
+
+Please see:
+
+- [How release please works](https://github.com/google-github-actions/release-please-action/tree/v4.0.2?tab=readme-ov-file#how-release-please-works)
+- [How do I change the version number?](https://github.com/googleapis/release-please/tree/v16.7.0?tab=readme-ov-file#how-do-i-change-the-version-number)
+- [How can I fix release notes?](https://github.com/googleapis/release-please/tree/v16.7.0?tab=readme-ov-file#how-can-i-fix-release-notes)
+
+## Merge release branch
+
+The release branch must be merged into main.
+Those merges need to happen via PRs.
+
+Example for PR titles:
+
+_build(1.2.0): merge release into main_
+
+> Be aware that the merge into main triggers the workflow with the [helm chart releaser action](../../.github/workflows/release.yaml).
+>
+> The workflow creates a 'centralidp-x.x.x' and 'sharedidp-x.x.x' tags and according releases. The release contains the new chart.
+>
+> This workflow also pushes the version tag that triggers the [release workflow](../../.github/workflows/release.yaml) which creates the versioned docker image/s.
+
+_environment relevant: The 'vx.x.x' tag is used to install (with the convenience of the argocd-app-templates) or upgrade the version via AgroCD on the hosted K8s clusters._
+
+## RC: provide successive rc branch and change base of open PRs
+
+During a release candidate phase, checkout the successive 'rc' branch and push it to the server, so that it can be used for further bugfixes.
+
+Example:
+
+```bash
+git checkout tags/v0.1.0-rc.2 -b release/v0.1.0-rc.3
+```
+
+Also make sure to change the base of all open pull requests still pointing to the previous 'rc' branch to the newly pushed 'rc' branch.
+
+## NOTICE
+
+This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+- SPDX-License-Identifier: Apache-2.0
+- SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation
+- Source URL: https://github.com/eclipse-tractusx/portal-iam