From fd3df7df6740d8e54b433c039d294843582e8947 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Thorsten=20Ro=C3=9Fner?= Date: Wed, 24 Jul 2024 09:51:08 +0200 Subject: [PATCH] fix(docs): Update workflow.md. --- docs/getting-started.md | 2 +- docs/workflow.md | 80 ++++++++++++++++------------------------- 2 files changed, 32 insertions(+), 50 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 9822fcb9..6aafaf05 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -3,7 +3,7 @@ SPDX-FileCopyrightText: 2023 Bundesministerium des Innern und für Heimat, PG Ze SPDX-License-Identifier: Apache-2.0 --> -

Getting stated

+

Getting started

This documentation should enable you to create your own evaluation instance of openDesk on your Kubernetes cluster. diff --git a/docs/workflow.md b/docs/workflow.md index b0fc4b95..5114f76c 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -22,8 +22,8 @@ SPDX-License-Identifier: Apache-2.0 * [Branch workflows](#branch-workflows) * [`main`](#main) * [`develop`](#develop) - * [`docu`](#docu) - * [`mntn`](#mntn) + * [`docs`](#docs) + * [`fix`](#fix) * [`feat`](#feat) * [Branch names](#branch-names) * [Commit messages / Conventional Commits](#commit-messages--conventional-commits) @@ -169,8 +169,8 @@ The basic facts for the flow are: - Developers can create sub-branches from their feature branch(es) as needed. - When a *feature* branch gets pushed a Merge Request in `Draft` state is automatically created. - We know three types of *feature* branches: - - `docu`: Doing just documentation changes - - `mntn`: Maintenance of the openDesk software components and minor configurational changes + - `docs`: Doing just documentation changes + - `fix`: Maintenance of the openDesk software components and minor configurational changes - `feat`: All changes that do not fall into the two categories above, especially - supplier deliverables and - configurational changes that have a significant impact on openDesk users or require migrations[^1] @@ -185,21 +185,21 @@ gitGraph checkout "develop" commit id: "QA 'nightly develop'" commit id: " " - branch "docu" - checkout "docu" + branch "docs" + checkout "docs" commit id: "Documentation commits" type: HIGHLIGHT checkout "develop" - merge "docu" + merge "docs" checkout "main" merge "develop" tag: "No release" checkout "develop" commit id: " " - branch "mntn" - checkout "mntn" + branch "fix" + checkout "fix" commit id: "Maintenance commits" type: HIGHLIGHT - commit id: "QG 'mntn'" type: REVERSE + commit id: "QG 'fix'" type: REVERSE checkout "develop" - merge "mntn" + merge "fix" commit id: "QA 'release merge'" type: REVERSE checkout "main" merge "develop" tag: "Patch or minor release" @@ -231,7 +231,7 @@ The Standard Quality Gate addresses quality assurance steps that should be execu 1. Linting - Blocking - Licensing: [reuse](https://github.com/fsfe/reuse-tool) - - openDesk specific: Especially `images.yaml` and `charts.yaml`, find more details in the [development](./development.md) docu + - openDesk specific: Especially `images.yaml` and `charts.yaml`, find more details in [development.md](./development.md). - Non Blocking - Security: [Kyverno policy check](../.kyverno) addressing some IT-Grundschutz requirements - Formal: Yaml @@ -277,8 +277,8 @@ This section will explain the workflow for each branch (type) based on the Gitfl - `QA 'nightly main'`: Execute the SQG based on the most recent release. The upgrade test environment should be a long-standing environment that only gets built from scratch with the previous technical release when something breaks the environment. - Merge points: We are using the [Semantic Release convention](https://github.com/semantic-release/semantic-release) which itself is based on the [Semantic Versioning (SemVer) notation](https://semver.org) to automatically create technical releases on the merge points. - - "No release": When a merge from `develop` includes only changes from `docu` branches the merge into `main` will only consist of `docs` or `chore` commits. No new release will be generated by that merge. - - "Patch or minor release": When changes from `mntn` branches get merged these might contain `fix` or `feat` commits causing a new technical release to be built with an updated version on Patch or Minor level. + - "No release": When a merge from `develop` includes only changes from `docs` branches the merge into `main` will only consist of `docs` or `chore` commits. No new release will be generated by that merge. + - "Patch or minor release": When changes from `fix` branches get merged these might contain `fix` or `feat` commits causing a new technical release to be built with an updated version on Patch or Minor level. - "Minor or major release": When changes from `feat` branches get merged these might contain `feat` commits even with breaking changes, causing a technical release to be built with an updated version on Minor or Major level. - "Manual Functional Release Activities": Technical releases are loosely coupled to functional releases. The additional activities for a functional release select an existing technical release as a basis to generate the artifacts required for a functional release, for example: - Conduct additional manual explorative and regression tests. @@ -289,19 +289,19 @@ This section will explain the workflow for each branch (type) based on the Gitfl - `QA 'nightly develop'`: Follows the same approach as `QA 'nightly main'` - execute the SQG based in this case on the head revision of the `develop` branch. - `QA 'release merge'`: The Merge Request for this merge has to be created manually by members of the platform development team. It should document: - That the SQG was successfully executed upon the to-be merged state - it could be done explicitly or based on a `QA 'nightly develop'` - - In case of `mntn` changes that usually how no test automation: Changes have been verified by a member of the platform development team. + - In case of `fix` changes that usually how no test automation: Changes have been verified by a member of the platform development team. - That the changes have been reviewed by at least two members of the platform development team giving their approval on the Merge Request. -- Merge points (from `docu`, `mntn`, and `feat` branches): No additional activity on these merge points as the QA is ensured before the merge in the just-named branch types. +- Merge points (from `docs`, `fix`, and `feat` branches): No additional activity on these merge points as the QA is ensured before the merge in the just-named branch types. -##### `docu` +##### `docs` -Branches of type `docu` only contain the commits themselves and have to adhere to the workflow basic fact that: +Branches of type `docs` only contain the commits themselves and have to adhere to the workflow basic fact that: > All merges into `develop` or `main` require two approvals from the platform development team. -##### `mntn` +##### `fix` -Besides the actual changes being committed in an `mntn` branch there is only the: -- `QG 'mntn'`: In addition to validating the actual change the owner of the branch has to ensure the successful execution of the SQG. +Besides the actual changes being committed in an `fix` branch there is only the: +- `QG 'fix'`: In addition to validating the actual change the owner of the branch has to ensure the successful execution of the SQG. ##### `feat` @@ -318,47 +318,29 @@ This branch type requires the most activities on top of the actual development: #### Branch names -Branches created from the `develop` branch have to adhere to the following notation: `///
`: +Branches created from the `develop` branch have to adhere to the following notation: `//
`: -- ``: An identifier for the developing party optionally plus the name of the developer or team working on that branch. The following two-letter shorthand notations should be used for the owner: - - Suppliers - - `co`: Collabora - - `cp`: CryptPad - - `el`: Element - - `nc`: Nextcloud - - `nd`: Nordeck - - `op`: OpenProject - - `ox`: Open-Xchange - - `uv`: Univention - - `xw`: XWiki - - Other - - `pd`: (openDesk) Platform Development - - `xx`: Other, not one of the parties mentioned before - -- ``: Based on the branch types described in this document valid values for type are - - `docu` - - `mntn` +- ``: From the list of branch types explained above: + - `docs` + - `fix` - `feat` - -- ``: Valid components are +- ``: Something that makes you identifiable as owner of the branch, e.g. the first letter of your first name followed by your family name. +- `
`: A very short note about what is going to happen in the branch and ideally what component is affected from the following list of components: - `helmfile` - `ci` - - `cross-functional` - `docs` - `collabora` - `cryptpad` - `element` - `jitsi` - `nextcloud` + - `nubus` - `open-xchange` - `openproject` - `services` - - `univention-management-stack` - `xwiki` -- `
`: A very short note about what is going to happen in the branch - -Example: `pd-tom/fix/open-xchange/bump_to_8.76`. +Example: `feat/tmueller/bump_nextcloud_to_29.0.0`. **Note**: The above naming convention is not enforced yet, but please ensure you make use of it. @@ -367,7 +349,7 @@ Example: `pd-tom/fix/open-xchange/bump_to_8.76`. Commit messages must adhere to the [Conventional Commit standard](https://www.conventionalcommits.org/en/v1.0.0/#summary). Commits that do not adhere to the standard get rejected by either [Gitlab push rules](https://docs.gitlab.com/ee/user/project/repository/push_rules.html) or the CI. ```text -(): [path/to/issue#1] +(): [path/to/issue#1] . │ │ │ │ │ │ | └─> Summary in present tense, sentence case, with no period at the end │ │ | @@ -378,7 +360,7 @@ Commit messages must adhere to the [Conventional Commit standard](https://www.co └─> Commit Type: chore, ci, docs, feat, fix ``` -Example: `fix(univention-management-stack): Update standard session timeout of openDesk realm in Keycloak` +Example: `fix(open-xchange): Bump to 8.26 to heal issue with functional mailbox provisioning.` **Beware**: The commit messages are an essential part of the [technical releases](https://gitlab.opencode.de/bmi/opendesk/deployment/sovereign-workplace/-/releases) as the release's notes are generated from the messages.