Add developer workflow

content/en/docs/contribution-guidelines/commit-messages.md

@@ -1,50 +1,79 @@
 ---
-title: Commit message naming conventions
-weight: 90
-description: Special keywords to reference tickets and control release notes
+title: Commit Message Conventions
+weight: 10
+description: Prefix tags for release notes, issue linking, and goreleaser integration
 tags: [Developer]
 ---
+
 ## Introduction
 
 ClusterCockpit uses [goreleaser](https://goreleaser.com/) for building and
-uploading releases. In this process the release notes including all notable
-changes are automatically generated based on special commit message tags.
-Moreover GitHub will parse special characters and words to link and close
-issues.
+uploading releases. Release notes are generated automatically from commit
+messages using the prefix tags described below. GitHub also parses special
+keywords to link commits and PRs to issues.
 
-## Reference issue tickets
+Before opening a pull request, use [interactive rebase]({{< ref "_index#interactive-rebase----cleaning-up-before-a-pr" >}})
+to clean up your branch history and ensure the final commit messages follow
+these conventions.
 
-It is good practice to always create a ticket for notable changes.
-This allows to comment and discuss about source code changes. Any commit that
-contributes to the ticket should reference the ticket id (in the commit message
-or description). This is achieved in GitHub by prefixing the ticket id with a
-number sign character (`#`):
+---
+
+## Release Note Prefixes
+
+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 |
+
+Commits without a recognised prefix are not included in the release notes.
+
+**Examples:**
 
-```txt
-This change contributes to #235
+```
+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
 ```
 
-GitHub will detect if a pull request or commit uses special keywords to close a
-ticket:
+---
 
-- close, closes, closed
-- fix, fixes, fixed
-- resolve, resolves, resolved
+## Referencing Issues
 
-The ticket will not be closed before the commit appears on the main branch.
-Example:
+It is good practice to create a GitHub issue for any notable change so that
+the motivation and discussion are preserved. Reference an issue in any commit
+message or PR description using the `#<number>` syntax:
 
-```txt
-This change fixes #423
 ```
+This change contributes to #235
+```
+
+---
+
+## Automatically Closing Issues
 
-## Control release notes with preconfigured commit message prefixes
+GitHub closes an issue automatically when a PR containing one of the following
+keywords merges into the default branch:
 
-Commits with one of the following prefixes will appear in the release notes:
+- `close`, `closes`, `closed`
+- `fix`, `fixes`, `fixed`
+- `resolve`, `resolves`, `resolved`
+
+The issue is not closed until the commit appears on `main`. Example:
+
+```
+fix: correct WAL rotation on partial flush
+
+Fixes #423
+```
 
-- **feat:** Mark a commit to contain changes related to new features
-- **fix:** Mark a commit to contain changes related to bug fixes
-- **sec:** Mark a commit to contain changes related to security fixes
-- **doc:** Mark a commit to contain changes related to documentation updates
-- **[feat|fix] dep:** Mark a commit that is related to a dependency introduction
-  or change
+Place the closing keyword in the PR description rather than a WIP commit
+message, since commit messages are often rewritten with interactive rebase
+before the PR is merged.

content/en/docs/contribution-guidelines/documentation.md

@@ -1,62 +1,64 @@
 ---
-title: Contribute documentation
-weight: 90
-description: How to contribute to the documentation website
+title: Contributing to Documentation
+weight: 40
+description: How to set up a local Hugo environment and contribute to the documentation website
+tags: [Developer]
 ---
-We use [Hugo](https://gohugo.io/) to format and generate our website, the
-[Docsy](https://github.com/google/docsy) theme for styling and site structure.
-Hugo is an open-source static site generator that provides us with templates,
-content organisation in a standard directory structure, and a website generation
-engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.
 
-All submissions, including submissions by project members, require review. We
-use GitHub pull requests for this purpose. Consult
-[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
+The ClusterCockpit documentation is built with [Hugo](https://gohugo.io/) using
+the [Docsy](https://github.com/google/docsy) theme. Pages are written in
+Markdown. Hugo wraps them into a static site with navigation, search, and
+versioning.
 
-## Quick start
+All documentation contributions follow the same branch and PR workflow
+described in the [Developer Workflow]({{< ref "_index" >}}) guide. The
+repository to fork or clone is
+[ClusterCockpit/cc-doc](https://github.com/ClusterCockpit/cc-doc).
 
-Here's a quick guide to updating the docs. It assumes you're familiar with the
-GitHub workflow and you're happy to use the automated preview of your doc
-updates:
+---
 
-1. Fork the [cc-docs repo](https://github.com/ClusterCockpit/cc-doc) on GitHub.
-1. Make your changes and send a pull request (PR).
-1. If you're not yet ready for a review, add "WIP" to the PR name to indicate
-  it's a work in progress.
-1. Preview the website locally as described beyond.
-1. Continue updating your doc and pushing your changes until you're happy with
-  the content.
-1. When you're ready for a review, add a comment to the PR, and remove any
-  "WIP" markers.
+## Local Setup
 
-## Updating a single page
+You need the **Hugo extended** version (for SCSS support), at minimum Hugo
+0.45 — the most recent available version is recommended.
 
-If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you:
+Clone the repository with submodules (required for the Docsy theme):
 
-1. Click **Edit this page** in the top right hand corner of the page.
-1. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
+```bash
+git clone --recurse-submodules https://github.com/ClusterCockpit/cc-doc.git
+cd cc-doc
+```
 
-## Previewing your changes locally
+Start the local development server:
 
-If you want to run your own local Hugo server to preview your changes as you work:
+```bash
+hugo server
+```
 
-1. Follow the instructions in [Getting started](https://www.docsy.dev/docs/get-started/) to install Hugo and any other tools you need. You'll need at least **Hugo version 0.45** (we recommend using the most recent available version), and it must be the **extended** version, which supports SCSS.
-1. Fork the [cc-docs](https://github.com/ClusterCockpit/cc-doc) repo into your own project, then create a local copy using `git clone`. Don’t forget to use `--recurse-submodules` or you won’t pull down some of the code you need to generate a working site.
+Your site is available at <http://localhost:1313/>. Hugo watches for file
+changes and automatically rebuilds and reloads the page.
 
-```sh
-git clone --recurse-submodules --depth 1 https://github.com/ClusterCockpit/cc-doc.git
-```
+---
 
-1. Run `hugo server` in the site root directory. By default your site will be available at <http://localhost:1313/>. Now that you're serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.
-1. Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.
+## Quick Edit via GitHub
 
-## Creating an issue
+For small corrections to an existing page, use the **Edit this page** link in
+the top-right corner of any documentation page. GitHub will prompt you to fork
+the repository if you have not already, open the file in edit mode, and guide
+you through creating a PR.
 
-If you've found a problem in the docs, but you're not sure how to fix it yourself, please create an issue in the [cc-docs](https://github.com/ClusterCockpit/cc-doc/issues). You can also create an issue about a specific page by clicking the **Create Issue** button in the top right hand corner of the page.
+---
+
+## Creating an Issue
+
+If you have found a problem but are not ready to fix it yourself, open an issue
+in the [cc-doc repository](https://github.com/ClusterCockpit/cc-doc/issues).
+You can also use the **Create Issue** button in the top-right corner of any
+documentation page.
+
+---
 
-## Useful resources
+## Useful Resources
 
-* [Docsy user guide](https://www.docsy.dev/docs/): All about Docsy, including how it manages navigation, look and feel, and multi-language support.
-* [Hugo documentation](https://gohugo.io/documentation/): Comprehensive reference for Hugo.
-* [Github Hello World!](https://guides.github.com/activities/hello-world/): A basic introduction to GitHub concepts and workflow.
+- [Docsy user guide](https://www.docsy.dev/docs/) — navigation, look and feel, multi-language support
+- [Hugo documentation](https://gohugo.io/documentation/) — comprehensive Hugo reference