-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
82 additions
and
40 deletions.
There are no files selected for viewing
122 changes: 82 additions & 40 deletions
122
docs/technical-documentation/release-process/Release Process.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,76 +1,118 @@ | ||
| # Release Process | ||
|
|
||
| The release process for a new version can roughly be divided in the following steps: | ||
| The release process for a new version can roughly be divided into the following steps: | ||
|
|
||
| * Preparation | ||
| * Build of a versioned image | ||
| * Release of a new helm chart version | ||
| * Merge upstream to eclipse-tractusx | ||
| - [Preparations on the release branch](#preparations-on-the-release-branch) | ||
| - [Update CHANGELOG.md](#update-changelogmd) | ||
| - [Tag and build of versioned images](#tag-and-build-of-versioned-images) | ||
| - [Create releases from tags](#create-releases-from-tags) | ||
| - [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) | ||
|
|
||
| The process builds on the development flow which takes place within the forks from eclipse-tractusx, located in the catenax-ng organization. | ||
| The process builds on the development flow which, usually, takes place within forks and leads to merged pull pull requests in the repositories of the eclipse-tractusx organization. | ||
|
|
||
| ## Preparation | ||
| For assigning and incrementing **version** numbers [Semantic Versioning](https://semver.org) is followed. | ||
|
|
||
| It's recommended to do step 1-3 in one preparatory pull request to main, or dev respectively. | ||
| ## Preparations on the release branch | ||
|
|
||
| ### 1. Update changelog file | ||
| Checking out from the dev branch (or main for portal-assets) a release branch (release/{to be released version} e.g. release/v1.2.0, or respectively release/v1.2.0-RC1 for a release candidate). | ||
| On the release branch the following steps are executed: | ||
|
|
||
| The changelog file tracks all notable changes since the last released version. | ||
| During development every developer should extend the changelog under the 'Unreleased' section when raising a pull request to main or dev. | ||
| Once a new version is ready to be released, the changelog of the version gets finalized and the release version gets set for the, up to then, unreleased changes. | ||
| In the released version, the changelog is structured as following: | ||
| ### 1. Aggregate migrations | ||
|
|
||
| Migrations should be **aggregated in the case of releasing a new version**, in order to not release the entire history of migrations which accumulate during the development process. | ||
|
|
||
| Once a version has been released, migrations **mustn't be aggregated** in order to ensure upgradeability this also applies to **release candidates > RC1 and hotfixes**. | ||
| Be aware that migrations coming release branches for release candidates or from hotfix branches, will **need to be incorporated into dev and main**. | ||
|
|
||
| * Changes | ||
| * Features | ||
| * Technical Support | ||
| * Bug Fixes | ||
| ### 2. Version bump | ||
|
|
||
| In case of breaking change, the breaking change will get highlighted with a breaking change tag =>  | ||
| The version needs to be updated in the `src` directory within the 'Directory.Build.props' file. | ||
|
|
||
| ### 2. Update dependencies file | ||
| Bump helm chart and image version (also for argocd-app-templates, needed for consortia-environments). | ||
|
|
||
| In order to have an up-to-date list, of the used third-party libraries, the dependencies file needs to be updated. | ||
| Example for commit message: | ||
|
|
||
| This can be done by running the following statement: | ||
| _release: bump version for vx.x.x_ | ||
|
|
||
| ### 3. Update README (on chart level) | ||
|
|
||
| Use [helm-docs](https://github.com/norwoodj/helm-docs) (gotemplate driven) for updating the README file. | ||
|
|
||
| ```bash | ||
| dotnet list src package --include-transitive > DEPENDENCIES-PREP | ||
| cat DEPENDENCIES-PREP | grep ">" | grep -Pv "\s(Org|Microsoft|NuGet|System|runtime|docker|Docker|NETStandard)" | sed -E -e "s/\s+> ([a-zA-Z\.\-]+).+\s([0-9]+\.[0-9]+\.[0-9]+)\s*/nuget\/nuget\/\-\/\1\/\2/g" > DEPENDENCIES | ||
| awk -i inplace '!seen[$0]++' DEPENDENCIES | ||
| helm-docs --chart-search-root [charts-dir] --sort-values-order file | ||
| ``` | ||
|
|
||
| Only commit the updated dependencies file, not the 'DEPENDENCIES-PREP' file. | ||
| Example for commit message: | ||
|
|
||
| _release: 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 gets automatically created by triggering the [release-please workflow](../../../.github/workflows/release-please.yml). | ||
|
|
||
| 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) | ||
|
|
||
| ## Tag and build of versioned images | ||
|
|
||
| ### 3. Version bump | ||
| It's important to pull the latest state of the release branch locally. | ||
| Then create and push a tag for the released version. | ||
| The push of the tag triggers the [release workflow](../../../.github/workflows/release.yml) which creates the versioned image/s. | ||
|
|
||
| To update the version please adjust the version in the `src` directory within the `Directory.Build.props` file. | ||
| Example for tag: | ||
|
|
||
| TODO (EG): we might add something here | ||
| _v0.1.0_ | ||
|
|
||
| ### 4. Merge from dev into main branch | ||
| Examples for tag messages: | ||
|
|
||
| The merge from dev into main, via pull request, needs to happen before releasing. | ||
| _Version 0.1.0: Policy-Hub for the Catena-X_ | ||
|
|
||
| ## Build of a versioned image | ||
| ## Create releases from tags | ||
|
|
||
| It's important to pull the latest state from main of every repository. | ||
| Then a tag for the released version (e.g. v0.10.0) needs to be created and pushed. | ||
| The push of the tag triggers the release workflow action (available in every repository) which creates the versioned image/s. | ||
| Create the release from the tag available in repository. | ||
|
|
||
| ## Release of a new helm chart version | ||
| Examples for release messages: | ||
|
|
||
| TODO (EG): depending on our process we need to add something here | ||
| _Version 0.1.0: Policy-Hub for the Catena-X_ | ||
|
|
||
| ## Merge upstream to eclipse-tractusx | ||
| ## Merge release branch | ||
|
|
||
| Once a new version has been released, it should be merged upstream to eclipse-tractusx and tagged. | ||
| The release branch must be is merged into main. | ||
| Afterwards, main into dev. | ||
| Those merges need to happen via PRs. | ||
|
|
||
| Example for PR titles: | ||
|
|
||
| _release(1.2.0): merge release into main_ | ||
|
|
||
| _release(1.2.0): merge main to dev_ | ||
|
|
||
| Be aware that merge into main trigger the workflow with the [helm-chart releaser](../../../.github/workflows/chart-release.yaml). | ||
|
|
||
| Besides the official chart itself, there is also created a 'policy-hub-x.x.x' tag. | ||
| This tag is used to install (with the convenience of the argocd-app-templates) or upgrade the version via AgroCD on the consortia 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 it used for further bugfixes. | ||
|
|
||
| Example: | ||
|
|
||
| ```bash | ||
| git checkout tags/v0.1.0-RC2 -b release/v0.1.0-RC3 | ||
| ``` | ||
|
|
||
| - https://github.com/eclipse-tractusx/policy-hub | ||
| 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: 2021-2023 Contributors to the Eclipse Foundation | ||
| - SPDX-FileCopyrightText: 2021-2024 Contributors to the Eclipse Foundation | ||
| - Source URL: https://github.com/eclipse-tractusx/policy-hub |