From 92c1bafcea9a2dfe3cff60f4f0f4bc5485c7a8d1 Mon Sep 17 00:00:00 2001 From: Jan Eitzinger Date: Wed, 1 Apr 2026 06:41:49 +0200 Subject: [PATCH] Review and adapt git workflow documentation --- .../en/docs/contribution-guidelines/_index.md | 32 ++++++++----------- .../commit-messages.md | 14 +++----- .../docs/contribution-guidelines/release.md | 14 ++++---- 3 files changed, 26 insertions(+), 34 deletions(-) diff --git a/content/en/docs/contribution-guidelines/_index.md b/content/en/docs/contribution-guidelines/_index.md index fc358ab..44c25e4 100644 --- a/content/en/docs/contribution-guidelines/_index.md +++ b/content/en/docs/contribution-guidelines/_index.md @@ -1,7 +1,7 @@ --- -title: Developer Workflow +title: Developer git Workflow description: > - Contributing to ClusterCockpit using GitHub Flow with git rebase. + How the ClusterCockpit team is using GitHub Flow with git rebase. weight: 80 tags: [Developer] --- @@ -26,7 +26,6 @@ with `origin` in the commands below. ```bash git config --global pull.rebase true -git config --global rebase.autoStash true ``` --- @@ -37,13 +36,11 @@ git config --global rebase.autoStash true /- ``` -| Prefix | Use for | -| --------------- | ----------------------------- | -| `feat/` | New features | -| `fix/` | Bug fixes | -| `sec/` | Security fixes | -| `doc/` | Documentation | -| `fix/backport-` | Backports to a release branch | +| Prefix | Use for | +| ------- | ------------- | +| `feat/` | New features | +| `fix/` | Bug fixes | +| `doc/` | Documentation | Examples: `feat/123-auto-job-tagging`, `fix/backport-423-wal-rotation-v1.3` @@ -56,7 +53,7 @@ Persistent release branches: `release/v1.x` (minor version only). 1. **Sync** `main` before starting: ```bash - git fetch upstream && git rebase upstream/main + git pull ``` 2. **Branch** off `main`: @@ -68,22 +65,24 @@ Persistent release branches: `release/v1.x` (minor version only). 3. **Commit** freely — informal messages are fine during development; they will be cleaned up before the PR. Reference issue numbers where relevant. -4. **Push**, and use `--force-with-lease` (never `--force`) after any rebase: +4. **Push**, and use optionally `--force-with-lease` (never `--force`) after any + rebase: ```bash git push -u origin feat/123-my-feature git push --force-with-lease origin feat/123-my-feature # after rebase ``` -5. **Rebase onto `main`** whenever the base branch has moved: +5. **Rebase onto `main`** whenever the base branch has moved to ensure feature + branch is compatible with latest upstream main: ```bash - git fetch upstream && git rebase upstream/main + git fetch origin && git rebase origin/main ``` --- -## Interactive Rebase Before Opening a PR +## Optional: Interactive Rebase Before Opening a PR Clean up the branch history so each commit is a logical unit with a proper prefix message before requesting review: @@ -102,9 +101,6 @@ required prefixes. Push with `--force-with-lease` afterwards. - [ ] Rebased on current `main`, no merge commits in the branch - [ ] Commit messages follow prefix conventions -- [ ] `make test` passes (see [Unit Tests]({{< ref "testing" >}})) -- [ ] Frontend build passes if frontend files changed (see [Frontend Development Setup]({{< ref "frontend-testing" >}})) -- [ ] No debug output or temporary code committed - [ ] Issue number referenced in a commit message or PR description - [ ] Docs updated if user-facing behaviour changed (see [Contributing to Documentation]({{< ref "documentation" >}})) diff --git a/content/en/docs/contribution-guidelines/commit-messages.md b/content/en/docs/contribution-guidelines/commit-messages.md index e9f6820..0f812de 100644 --- a/content/en/docs/contribution-guidelines/commit-messages.md +++ b/content/en/docs/contribution-guidelines/commit-messages.md @@ -23,13 +23,11 @@ these conventions. Commits carrying one of the following prefixes appear in the generated release notes: -| Prefix | Appears under | -|---|---| -| `feat:` | New features | -| `fix:` | Bug fixes | -| `sec:` | Security fixes (ClusterCockpit-specific) | -| `doc:` | Documentation updates | -| `feat dep:` or `fix dep:` | Dependency additions or changes | +| Prefix | Appears under | +| ------- | --------------------- | +| `feat:` | New features | +| `fix:` | Bug fixes | +| `doc:` | Documentation updates | Commits without a recognised prefix are not included in the release notes. @@ -38,9 +36,7 @@ Commits without a recognised prefix are not included in the release notes. ``` feat: add automatic job tagging fix: correct WAL rotation on partial flush (#423) -sec: enforce API token expiry doc: update rebase workflow guide -feat dep: upgrade to Go 1.22 ``` --- diff --git a/content/en/docs/contribution-guidelines/release.md b/content/en/docs/contribution-guidelines/release.md index 7c5e67e..ba7739d 100644 --- a/content/en/docs/contribution-guidelines/release.md +++ b/content/en/docs/contribution-guidelines/release.md @@ -11,9 +11,9 @@ tags: [Developer] ClusterCockpit maintains two types of long-lived branches: -| Branch | Purpose | -|---|---| -| `main` | Active development; all new features and fixes land here first | +| Branch | Purpose | +| -------------- | ----------------------------------------------------------------------- | +| `main` | Active development; all new features and fixes land here first | | `release/v1.x` | Persistent branch for a minor release series; receives backported fixes | A `release/v1.x` branch is created once when cutting a new minor or major @@ -37,7 +37,7 @@ Ensure all PRs intended for the release are merged and CI is green on `main`. ```bash git checkout main -git pull --rebase +git pull git checkout -b release/v1.x git push -u origin release/v1.x ``` @@ -64,7 +64,7 @@ On a Linux host with repository push access: ```bash git fetch origin git checkout release/v1.x -git pull --rebase +git pull git tag v1.x.0 -m "release v1.x.0" git push origin v1.x.0 ``` @@ -105,7 +105,7 @@ a PR. Note the commit SHA(s) of the fix once merged. ```bash git fetch origin git checkout release/v1.x -git pull --rebase +git pull git checkout -b fix/backport-- ``` @@ -140,7 +140,7 @@ After the backport PR is merged: ```bash git fetch origin git checkout release/v1.x -git pull --rebase +git pull git tag v1.x.1 -m "release v1.x.1" git push origin v1.x.1 goreleaser release