diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 62d99a8c..afd21191 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -116,5 +116,5 @@ jobs: --url https://api.github.com/repos/eclipse-tractusx/portal/actions/workflows/portal-assets-image-update.yml/dispatches \ --header "authorization: Bearer $TOKEN" \ --header "Accept: application/vnd.github.v3+json" \ - --data '{"ref":"dev", "inputs": { "new-image":"${{ github.sha }}" }}' \ + --data '{"ref":"main", "inputs": { "new-image":"${{ github.sha }}" }}' \ --fail diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3f74842e..7874b0d6 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -162,7 +162,7 @@ jobs: if [[ ${{ steps.rc-check.outputs.rc }} == 'true' ]]; then echo "branch=release-candidate" >> $GITHUB_OUTPUT else - echo "branch=dev" >> $GITHUB_OUTPUT + echo "branch=main" >> $GITHUB_OUTPUT fi if: steps.hf-check.outputs.hf == 'false' diff --git a/docs/developer/Technical Documentation/Dev Process/Dev-flow_deploy-dev-env.md b/docs/developer/Technical Documentation/Dev Process/Dev-flow_deploy-dev-env.md index 38f1d0f9..29da496d 100644 --- a/docs/developer/Technical Documentation/Dev Process/Dev-flow_deploy-dev-env.md +++ b/docs/developer/Technical Documentation/Dev Process/Dev-flow_deploy-dev-env.md @@ -8,10 +8,10 @@ flowchart LR subgraph eclipse-tractusx direction LR subgraph CI repos - D -- PR to dev* --> PF(portal-frontend**) - D -- PR to dev* --> PR(portal-registration**) + D -- PR to main* --> PF(portal-frontend**) + D -- PR to main* --> PR(portal-registration**) D -- PR* to main* --> PA(portal-assets**) - D -- PR* to dev*--> PB(portal-backend***) + D -- PR* to main*--> PB(portal-backend***) click PF "https://github.com/eclipse-tractusx/portal-frontend" click PR "https://github.com/eclipse-tractusx/portal-frontend-registration" click PA "https://github.com/eclipse-tractusx/portal-assets" @@ -23,13 +23,13 @@ flowchart LR PI --> PICD(portal-iam -b main) click PI "https://github.com/eclipse-tractusx/portal-iam" end - subgraph CD repo for auto-deploy to dev + subgraph CD repo with helm chart for auto-deploy to dev direction LR - PF --> CD(portal***** -b dev) + PF --> CD(portal***** -b main) PR --> CD PB --> CD PA --> CD - D -- PR* to -b dev for chart --> CD + D -- PR* to -b main --> CD click CD "https://github.com/eclipse-tractusx/portal" end end @@ -41,13 +41,13 @@ flowchart LR Note\* Every pull request (PR) requires at least one approving review by a committer -Note\*\* ESlint, unit tests and Sonarcloud runs at pull request, Trivy and KICS scans at merge as well as daily and Veracode scan runs weekly +Note\*\* ESlint, unit tests, Sonarcloud, CodeQL checks run at pull request, Trivy and KICS scans run at push on main as well as daily -Note\*\*\* Unit tests and Sonarcloud runs at pull request, Trivy and KICS scans at merge as well as daily and Veracode scan runs weekly +Note\*\*\* Unit tests and Sonarcloud, CodeQL checks run at pull request, Trivy and KICS scans run at push on main as well as daily -Note\*\*\*\* Sonarcloud runs at pull request, Trivy and KICS scans at merge as well as daily +Note\*\*\*\* Sonarcloud runs at pull request, Trivy and KICS scans run at push on main as well as daily -Note**\*** Trivy and KICS scans are scheduled to daily +Note**\*** Trivy and KICS scans run at push on main as well as daily ## NOTICE diff --git a/docs/developer/Technical Documentation/Dev Process/Dev-flow_git-diagram.md b/docs/developer/Technical Documentation/Dev Process/Dev-flow_git-diagram.md index aa700dfc..46d78b79 100644 --- a/docs/developer/Technical Documentation/Dev Process/Dev-flow_git-diagram.md +++ b/docs/developer/Technical Documentation/Dev Process/Dev-flow_git-diagram.md @@ -3,125 +3,61 @@ ```mermaid %%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% gitGraph - commit id: "release: v1.0.0" tag:"1.0.0" - branch dev order: 1 - checkout dev - branch feature/feature1 order: 2 - commit id:"feat(function): add feature1" - checkout dev - branch bug/bug1 order: 3 - commit id: "fix(function): change bug1" - checkout dev - branch feature/feature2 order: 4 - commit id:"feat(function)!: enable feature2" - checkout bug/bug1 - commit id:"fix(function): refactor bug1" - checkout dev - merge bug/bug1 - checkout dev - branch feature/feature3 order: 5 - commit id:"feat(function): wip - enable feature3" - checkout dev - checkout feature/feature3 - commit id: "feat(function): enable feature3" - checkout dev - merge feature/feature3 + commit id: "chore: initial commit" + branch feature/feature1 order: 1 checkout feature/feature1 - commit id:"feat(function): enable feature1" - checkout dev + commit id:"feat(function): add feature1" + checkout main merge feature/feature1 - branch release/1.1.0 order: 6 - commit id: "release(1.1.0): aggregate migrations (backend)" - commit id: "release(1.1.0): update version, changelog..." tag: "1.1.0" + 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 release/1.1.0 id: "1. merge into main" - checkout dev - merge main id: "2. merge main into dev" - checkout dev - branch feature/feature4 order: 7 - commit id: "feat(function): add feature4" + merge bug/bug1 checkout feature/feature2 - commit id: "feat(function)!: change feature2" - checkout dev + commit id:"feat(function)!: finalize feature2" + checkout main merge feature/feature2 - checkout feature/feature4 - commit id: "feat(function): change feature4" - checkout dev - merge feature/feature4 - branch release/1.2.0 order: 8 - commit id: "release(1.2.0-RC1): prepare migration (backend)" - commit id: "release(1.2.0-RC1): update version, changelog..." tag: "1.2.0-RC1" + branch feature/feature3 order: 4 + commit id:"feat(function)!: WIP enable feature3" checkout main - merge release/1.2.0 - checkout dev - merge main - checkout release/1.2.0 - branch bug/bug2 order: 9 - commit id:"fix(function): change1 bug2" - checkout release/1.2.0 - branch bug/bug3 order: 10 - commit id:"fix(function): change bug3" - checkout release/1.2.0 - merge bug/bug3 - merge dev - checkout dev - branch feature/feature5 order: 11 - commit id: "feat(function): add feature5" + 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): change2 bug2" - checkout release/1.2.0 + 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: "release(1.2.0-RC2): update version, changelog..." tag: "1.2.0-RC2" + commit id: "build(v1.0.0-rc.2): bump version" tag: "v1.0.0-rc.2" checkout main - merge release/1.2.0 - checkout dev - merge main - checkout dev - branch feature/feature6 order: 12 - commit id: "feat(function): add feature for 1.4.0" - checkout feature/feature5 - commit id: "feat(function): change feature5" - checkout dev - merge feature/feature5 - branch release/1.3.0 order: 13 - commit id: "release(1.3.0): aggregate migrations (backend)" - commit id: "release(1.3.0): update version, changelog..." tag: "1.3.0" - checkout main - merge release/1.3.0 - checkout dev - merge main - checkout feature/feature6 - commit id: "feat(function): change feature for 1.4.0" - merge dev - checkout release/1.2.0 - branch bug/bug4 order: 14 - commit id:"fix(function): change1 bug4" - commit id:"fix(function): change2 bug4" - checkout release/1.2.0 - merge bug/bug4 - commit id: "release(1.2.0): update version, changelog..." tag: "1.2.0" + merge release/v1.0.0-rc.2 + checkout feature/feature3 + commit id:"feat(function)!: finalize feature3" checkout main - merge release/1.2.0 - checkout dev - merge main - checkout release/1.2.0 - branch hotfix/1.2.1 order: 15 - branch bug/bug5 order: 16 - commit id:"fix(function): change1 bug5" - checkout hotfix/1.2.1 - branch bug/bug6 order: 17 - commit id:"fix(function): change bug6" - checkout hotfix/1.2.1 - merge bug/bug6 - checkout bug/bug5 - commit id:"fix(function): change2 bug5" - checkout hotfix/1.2.1 - merge bug/bug5 - commit id: "hotfix(1.2.1): update version, changelog..." tag: "1.2.1" + 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 hotfix/1.2.1 - checkout dev - merge 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 diff --git a/docs/developer/Technical Documentation/Dev Process/How to contribute.md b/docs/developer/Technical Documentation/Dev Process/How to contribute.md index 8472741e..0c992115 100644 --- a/docs/developer/Technical Documentation/Dev Process/How to contribute.md +++ b/docs/developer/Technical Documentation/Dev Process/How to contribute.md @@ -1,101 +1,100 @@ # Contribution details -To contribute to the portal as part of the open source community, please read the details defined below. +To contribute to the Portal as part of the open source community, please read the details defined below. Besides a generic "how to", some commit and pull request (PR) guidelines are defined to ensure readability and make newly created PRs easier to review. Additionally, changelogs can get validated as well as written with more ease. Moreover, similar patterns are in use across the contributor community. **Content**: - [Commit How To](#how-to-contribute) -- [Commit and PR guidelines](#commit-and-pr-guidelines) +- [Commits, branches and pull requests guidelines](#commits-branches-and-pull-requests-guidelines) ## How To Contribute ### 1 Create a fork -Open github - "eclipse-tractusx" project and select the respective repository to which you want to contribute. +Open [GitHub - "eclipse-tractusx" project](https://github.com/eclipse-tractusx) and select the respective repository to which you want to contribute. [Create a fork of the respective repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo). ### 2 Fork setup -Setup your fork by entering a name and make sure that you unselect the "main branch only" selection, in case the original repository has a dev and a main branch. +Setup your fork by entering a name and make sure that you unselect the "main branch only" selection, in case the upstream repository maintains release branches besides the main branch. -Click "Create fork" +Click "Create fork". ### 3 Commit With the newly created fork, you can now start to contribute. Create a new branch in your own fork and start to implement the planned changes or new features. -When the implementation is ready, create a PR against the original repository. +When the implementation is ready, create a PR against the upstream repository. The PR will get reviewed by the repository owners/official committers. -As part of the pr review, sonarcloud will run automatically, and unit tests (if configured) will get executed. The PR owner is responsible to check the results and fix possible findings. +As part of the PR review, checks will run automatically, and unit tests (if configured) will get executed. The PR owner is responsible to check the results and fix possible findings. -## Commit and PR guidelines +## Commits, branches and pull requests guidelines -### Commits +### Commits and branches The suggestion is to use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). -Here are some examples +Here are some examples: -Feature branch: +#### Feature branch ```mermaid %%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% gitGraph - commit id: "release(1.0.0): merge in main" - branch dev order: 1 - checkout dev + commit id: "chore: initial commit" branch feature/feature1 order: 2 commit id:"feat(function): add feature1" commit id:"feat(function): enable feature1" + checkout main + merge feature/feature1 ``` -Bugfix branch: +#### Bugfix branch ```mermaid %%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% gitGraph - commit id: "release(1.0.0): merge in main" - branch dev order: 1 - checkout dev - branch bug/bug1 order: 3 - commit id: "fix(function): change bug1" + commit id: "build(v0.1.0): merge in main" + branch bug/bug1 order: 2 + commit id: "fix(function): change bug" checkout bug/bug1 - commit id:"fix(function): refactor bug1" + commit id:"fix(function): refactor bug" + checkout main + merge bug/bug1 ``` -Release branch: +#### Release branch ```mermaid %%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% gitGraph - commit id: "release: v1.0.0" - branch dev order: 1 - checkout dev - branch release/1.1.0 order: 2 - commit id: "release(1.1.0): aggregate migrations (backend)" - commit id: "release(1.1.0): update version, changelog..." tag: "1.1.0" + commit id: "build(v0.1.0): merge in main" + branch release/v1.0.0 order: 2 + commit id: "build(v1.0.0): bump version, changelog..." tag: "v1.0.0" + checkout main + merge release/v1.0.0 ``` -Hotfix branch: +#### Hotfix branch ```mermaid %%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% gitGraph commit id: "release: v1.0.0" - branch dev order: 1 - checkout dev - branch release/1.1.0 order: 2 - commit id: "release(1.1.0): aggregate migrations (backend)" - commit id: "release(1.1.0): update version, changelog..." tag: "1.1.0" - checkout release/1.1.0 - branch hotfix/1.1.1 order: 3 - commit id: "hotfix(1.1.1): update version, changelog..." tag: "1.1.1" + branch release/v1.0.0 order: 2 + commit id: "build(v1.0.0): bump version, changelog..." tag: "v1.0.0" + checkout main + merge release/v1.0.0 + checkout release/v1.0.0 + branch hotfix/v1.0.1 order: 3 + checkout hotfix/v1.0.1 + commit id: "hotfix(v1.0.1): bump version, changelog..." tag: "v1.0.1" ``` ### PR title -The suggested naming convention is '{type}{(function)}: {short summary}' +The suggested naming convention is '{type}{(function)}: {short summary}'. ### PR description @@ -112,6 +111,10 @@ If your change includes adding pictures, please add them in the following way: The absolute path in step 3 is necessary because the documentation app is not yet enabled for relative paths: [#236](https://github.com/eclipse-tractusx/portal-assets/issues/236). +### Additional information + +Please refer to the [Development Flow](./Dev-flow_git-diagram.md). + ## NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/docs/developer/Technical Documentation/Operations/Release-Process.md b/docs/developer/Technical Documentation/Operations/Release-Process.md index 6d3d7b9f..299c0b2b 100644 --- a/docs/developer/Technical Documentation/Operations/Release-Process.md +++ b/docs/developer/Technical Documentation/Operations/Release-Process.md @@ -10,7 +10,7 @@ The release process for a new version can roughly be divided into the following - [RC: provide successive RC branch and change base of open PRs](#rc-provide-successive-rc-branch-and-change-base-of-open-prs) - [Create releases from tags](#create-releases-from-tags) -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. +The process builds on the [Development Flow](./Dev-flow_git-diagram.md) which usually takes place within forks and leads to merged pull requests in the repositories of the eclipse-tractusx organization. Frontend repositories: @@ -30,7 +30,7 @@ For assigning and incrementing **version** numbers [Semantic Versioning](https:/ ## Preparations on the release branch -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). +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-RC1 for a release candidate). On the release branch the following steps are executed: ### 1. Version bump @@ -45,12 +45,12 @@ For the backend repo, the version needs to be updated within the 'Directory.Buil Example for commit message: -_release: bump version for vx.x.x_ +_build: bump version for vx.x.x_ ### 2. Update changelog file 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. +During development every developer should extend the changelog under the 'Unreleased' section when raising a pull request to main. 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: @@ -64,25 +64,25 @@ In case of breaking change, the breaking change will get highlighted with a brea Example for commit message: -_release: update changelog for vx.x.x_ +_docs: update changelog for vx.x.x_ ### 3. Aggregate migrations (backend repo only) 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**. +Be aware that migrations coming release branches for release candidates or from hotfix branches, will **need to be incorporated into main**. ## RC: checkout release-candidate branch -If starting into a release candidate phase, make sure to checkout the release-candidate branch from dev branch of [Portal](https://github.com/eclipse-tractusx/portal). +If starting into a release candidate phase, make sure to checkout the release-candidate branch from main branch of [Portal](https://github.com/eclipse-tractusx/portal). ## Tag and build of versioned images It's important to pull the latest state of the release branch locally in every repository. Then create and push a tag for the released version. The push of the tag triggers the release workflow action (available in every repository) which creates the versioned image/s. -The push also triggers the image tags to be updated in the helm chart: in the dev branch or respectively the release-candidate branch of the [Portal](https://github.com/eclipse-tractusx/portal) repository. +The push also triggers the image tags to be updated in the helm chart - in the main branch or respectively the release-candidate branch of the [Portal](https://github.com/eclipse-tractusx/portal) repository. Example for tag: @@ -103,7 +103,7 @@ _Version 1.1.0: Backend for the Catena-X Portal_ Once the versioned images are available, a new version of the chart can be released. The helm chart is released from [Portal](https://github.com/eclipse-tractusx/portal). -Check out a release branch from the dev branch or from the release-candidate branch respectively. +Check out a release branch from the main branch or from the release-candidate branch respectively. On the release branch the following steps are executed: 1. Bump chart and image version (also for argocd-app-templates, needed for consortia-environments) @@ -120,17 +120,17 @@ helm-docs --chart-search-root [charts-dir] --sort-values-order file Example for commit message: -_release: update readme for vx.x.x_ +_build: update readme for vx.x.x_ Once the steps are done, create a PR to 'main' to test the to be released helm chart with the 'Portal Lint and Test Chart' workflow. Example for PR title: -_release(1.2.0): merge release into dev_ +_build(1.2.0): merge release into main_ Once the workflow ran successfully, release the new helm chart by running the 'Release Chart' action via workflow dispatch on the release branch. -Then merge the release branch into 'main' and merge afterwards 'main' in 'dev'. In the case of a release candidate, the release branch also needs to be merged into the release-candidate branch. +Then merge the release branch into 'main'. In the case of a release candidate, the release branch also needs to be merged into the release-candidate branch. At the release of the chart, besides the official chart itself, there is also created a 'portal-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. @@ -152,16 +152,13 @@ Also make sure to change the base of all open pull requests still pointing to th ## Merge release branch The release branches must be is merged into main. -Afterwards, main into dev. This is only necessary for repositories with a dev branch. -Those merges need to happen via PRs. +This merge needs to happen via PR. -Technically this step is already possible after [Tag and build of versioned images](#tag-and-build-of-versioned-images), but it's recommended to execute this step after [Release new helm chart version](#release-new-helm-chart-version), so that the image tag for the release isn't overwritten by the merge into dev or main respectively. +Technically this step is already possible after [Tag and build of versioned images](#tag-and-build-of-versioned-images), but it's recommended to execute this step after [Release new helm chart version](#release-new-helm-chart-version), so that the image tag for the release isn't overwritten by the merge into main. Example for PR titles: -_release(1.2.0): merge release into main_ - -_release(1.2.0): merge main to dev_ +_build(1.2.0): merge release into main_ ## Create releases from tags