From aa914503d985bd1573a5e447a138ec9f46ee5ede Mon Sep 17 00:00:00 2001
From: Peter Vinter <peter.winther@gmail.com>
Date: Wed, 20 Nov 2024 01:05:19 +0100
Subject: [PATCH] docs: add comprehensive branch workflow and changelog
 documentation

---
 README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)

diff --git a/README.md b/README.md
index ed23241..26eb7d9 100644
--- a/README.md
+++ b/README.md
@@ -220,6 +220,117 @@ Follow the [Conventional Commits](https://www.conventionalcommits.org/) specific
 - `refactor:` Code improvements
 - `test:` Test updates
 
+### Development Workflow
+
+Our project follows a structured branching strategy to maintain code quality and automate changelog updates. Here's how to work with our workflow:
+
+#### Branch Structure
+- `main`: Production-ready code
+- `develop`: Integration branch for features
+- `feature/*`: Individual feature branches
+- `fix/*`: Bug fix branches
+- `docs/*`: Documentation updates
+
+#### Making Changes
+
+1. **Create Feature Branch**
+   ```bash
+   # For new features
+   git checkout develop
+   git pull origin develop
+   git checkout -b feature/your-feature-name
+
+   # For documentation changes
+   git checkout develop
+   git pull origin develop
+   git checkout -b docs/update-description
+   ```
+
+2. **Make Changes**
+   - Follow commit message conventions:
+     - `feat:` for new features
+     - `fix:` for bug fixes
+     - `docs:` for documentation
+     - `!` or `BREAKING CHANGE` for breaking changes
+   
+   Example commit messages:
+   ```bash
+   git commit -m "feat: add new container logging"
+   git commit -m "fix: resolve startup script issue"
+   git commit -m "docs: update workflow guide"
+   git commit -m "feat!: change API response format"
+   ```
+
+3. **Push Changes**
+   ```bash
+   git push origin your-branch-name
+   ```
+
+4. **Create Pull Request**
+   - Create PR to `develop` branch
+   - Use descriptive title following commit conventions
+   - Fill out PR template
+   - Request review if needed
+
+5. **Merge to Develop**
+   - Ensure CI passes
+   - Get approvals if required
+   - Merge using "Merge commit"
+
+6. **Release to Main**
+   - Create PR from `develop` to `main`
+   - Our workflow will:
+     - Auto-increment version based on changes
+     - Update changelog automatically
+     - Create release tag
+
+#### Changelog Automation
+
+Our changelog is automatically managed through PRs:
+
+1. **Version Bumping**
+   - Major (2.0.0 → 3.0.0): PR title contains `!` or `BREAKING CHANGE`
+   - Minor (2.0.0 → 2.1.0): PR title starts with `feat:`
+   - Patch (2.0.0 → 2.0.1): All other changes
+
+2. **Entry Categories**
+   - Added: New features
+   - Changed: Changes in existing functionality
+   - Deprecated: Soon-to-be removed features
+   - Removed: Removed features
+   - Fixed: Bug fixes
+   - Security: Vulnerability fixes
+
+3. **Process Flow**
+   - Merge PR → Workflow detects changes
+   - Creates changelog entry
+   - Updates version number
+   - Creates new PR with changes
+   - Auto-merges changelog update
+
+#### Best Practices
+
+1. **Branch Naming**
+   - Features: `feature/descriptive-name`
+   - Fixes: `fix/issue-description`
+   - Docs: `docs/update-topic`
+
+2. **Commit Messages**
+   - Be descriptive but concise
+   - Follow conventional commits
+   - Reference issues when applicable
+
+3. **PR Guidelines**
+   - One feature/fix per PR
+   - Keep changes focused
+   - Update tests if needed
+   - Include documentation updates
+
+4. **Documentation**
+   - Update README for new features
+   - Keep code comments current
+   - Update API docs if changed
+
 ## Contributing
 
 Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests.