Skip to content

Commit bfdac26

Browse files
pvliesdonkpvliesdonk
authored
fix: fixes to release workflow
Next
2 parents 58b0fd9 + 7cbcac2 commit bfdac26

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1885
-365
lines changed

‎.github/workflows/ci.yaml‎

Lines changed: 369 additions & 94 deletions
Large diffs are not rendered by default.

‎BRANCHING_STRATEGY.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Branching Strategy
2+
3+
This repository follows a **main/next** branching model to ensure stable releases while allowing for continuous development.
4+
5+
## Branch Overview
6+
7+
### `main` Branch
8+
- **Purpose**: Production-ready code
9+
- **Protection**: Only accepts PRs from `next` branch (enforced by CI)
10+
- **Releases**: Stable releases (e.g., v1.2.0, v1.3.0)
11+
- **CI/CD**: Full test suite, security scans, and release automation
12+
13+
### `next` Branch
14+
- **Purpose**: Integration branch for upcoming releases
15+
- **Protection**: Accepts PRs from feature branches
16+
- **Releases**: Pre-releases (e.g., v1.3.0-next.1, v1.3.0-next.2)
17+
- **CI/CD**: Full test suite and security scans
18+
19+
## Workflow
20+
21+
### For Feature Development
22+
23+
1. **Create your feature branch from `next`**:
24+
```bash
25+
git checkout next
26+
git pull origin next
27+
git checkout -b feature/my-feature
28+
```
29+
30+
2. **Develop and test your changes**:
31+
```bash
32+
# Make your changes
33+
git add .
34+
git commit -m "feat: add new feature"
35+
```
36+
37+
3. **Submit PR to `next` branch**:
38+
- Target branch: `next`
39+
- Get review and approval
40+
- Merge to `next`
41+
42+
4. **Testing in `next`**:
43+
- Your changes are now in `next`
44+
- Pre-release version created (e.g., v1.3.0-next.1)
45+
- Can be tested in staging environments
46+
47+
### For Release to Production
48+
49+
1. **Create PR from `next` to `main`**:
50+
- Only when `next` is stable and ready for release
51+
- Typically done by maintainers
52+
- Triggers full CI/CD pipeline
53+
54+
2. **Merge to `main`**:
55+
- Creates stable release (e.g., v1.3.0)
56+
- Publishes to PyPI (if configured)
57+
- Updates documentation
58+
59+
3. **Sync `next` with `main`** (if needed):
60+
```bash
61+
git checkout next
62+
git merge main
63+
git push origin next
64+
```
65+
66+
## Branch Protection Rules
67+
68+
### Automated Protection (CI Enforcement)
69+
The `check-source-branch` job in `.github/workflows/ci.yaml` enforces that:
70+
- PRs to `main` must come from `next` branch only
71+
- PRs violating this rule will **fail CI** and cannot be merged
72+
- All other CI jobs are blocked until this check passes
73+
- Helpful comment is posted explaining the violation
74+
75+
### How It Works
76+
When you create a PR:
77+
1. The `check-source-branch` job runs first
78+
2. If targeting `main` from any branch other than `next`, it fails
79+
3. All other jobs (tests, security scans, etc.) are skipped
80+
4. A comment explains how to fix the issue
81+
82+
### Recommended GitHub Settings
83+
Configure these in **Settings → Branches → Branch protection rules**:
84+
85+
#### For `main` branch:
86+
- ✅ Require pull request reviews before merging (1 approval)
87+
- ✅ Require status checks to pass before merging
88+
- Required checks: `check-source-branch`, `test`, `test-e2e`, `security`
89+
- ✅ Require branches to be up to date before merging
90+
- ✅ Do not allow bypassing the above settings
91+
92+
#### For `next` branch:
93+
- ✅ Require pull request reviews before merging (1 approval)
94+
- ✅ Require status checks to pass before merging
95+
- Required checks: `test`, `test-e2e`, `security`
96+
- ✅ Require branches to be up to date before merging
97+
98+
## Hotfixes
99+
100+
For urgent production fixes:
101+
102+
1. **Create hotfix branch from `main`**:
103+
```bash
104+
git checkout main
105+
git pull origin main
106+
git checkout -b hotfix/critical-bug
107+
```
108+
109+
2. **Make minimal fix**:
110+
```bash
111+
# Fix the bug
112+
git add .
113+
git commit -m "fix: critical security issue"
114+
```
115+
116+
3. **Submit PR to `next` first**:
117+
- Even hotfixes should go through `next`
118+
- Allows for testing in pre-release
119+
- Merge to `next`, then immediately create PR to `main`
120+
121+
4. **Fast-track if critical**:
122+
- Get expedited review
123+
- Merge `next` → `main` quickly after verification
124+
125+
## Troubleshooting
126+
127+
### "check-source-branch failed" Error
128+
129+
**Problem**: You created a PR from your feature branch directly to `main`.
130+
131+
**Solution**:
132+
1. Close the PR to `main`
133+
2. Create a new PR from your feature branch to `next`
134+
3. After merge to `next`, a maintainer will create PR from `next` → `main`
135+
136+
### Merge Conflicts
137+
138+
If `next` has conflicts with `main`:
139+
```bash
140+
git checkout next
141+
git merge main
142+
# Resolve conflicts
143+
git commit
144+
git push origin next
145+
```
146+
147+
## Benefits of This Strategy
148+
149+
1. **Stability**: `main` always contains tested, production-ready code
150+
2. **Continuous Integration**: `next` allows ongoing development without blocking
151+
3. **Pre-release Testing**: Features can be tested in staging before production
152+
4. **Clear History**: Easy to see what's in production vs. what's coming next
153+
5. **Automated Protection**: CI enforcement prevents accidental direct merges to `main`
154+
6. **No Manual Oversight**: Violations are caught automatically before any reviewer sees them
155+
156+
## Questions?
157+
158+
If you have questions about the branching strategy, please:
159+
- Check existing GitHub discussions
160+
- Ask in PR comments
161+
- Contact the maintainers

‎CONTRIBUTING.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -53,15 +53,23 @@ We are committed to providing a welcoming and inclusive environment for all cont
5353

5454
### Branch Strategy
5555

56-
- `main` - Production-ready code
57-
- `feature/*` - New features
58-
- `fix/*` - Bug fixes
59-
- `docs/*` - Documentation updates
60-
- `refactor/*` - Code refactoring
56+
**Important**: We use a `main`/`next` branching model. Please read [BRANCHING_STRATEGY.md](BRANCHING_STRATEGY.md) for full details.
57+
58+
**Quick Summary**:
59+
- `main` - Production-ready code (only accepts PRs from `next`)
60+
- `next` - Integration branch for upcoming releases
61+
- `feature/*` - New features (submit PRs to `next`)
62+
- `fix/*` - Bug fixes (submit PRs to `next`)
63+
- `docs/*` - Documentation updates (submit PRs to `next`)
64+
- `refactor/*` - Code refactoring (submit PRs to `next`)
6165

6266
### Creating a Feature Branch
6367

68+
**Always branch from `next`**:
69+
6470
```bash
71+
git checkout next
72+
git pull origin next
6573
git checkout -b feature/amazing-feature
6674
```
6775

‎Dockerfile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ COPY uv.lock .
1212
COPY README.md .
1313
COPY src ./src
1414

15+
# Set a fallback version for hatch-vcs since .git is not available
16+
ENV SETUPTOOLS_SCM_PRETEND_VERSION=0.1.0
17+
1518
# Install dependencies
1619
RUN uv sync --frozen --no-dev
1720

@@ -21,7 +24,7 @@ FROM python:3.11-slim-bookworm
2124
# Install Docker CLI (for docker operations)
2225
RUN apt-get update && \
2326
apt-get install -y --no-install-recommends \
24-
docker.io && \
27+
docker.io=20.10.* && \
2528
rm -rf /var/lib/apt/lists/*
2629

2730
# Create non-root user

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -488,15 +488,17 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
488488
- Code style requirements
489489
- Submission process
490490

491+
**Important**: We use a `main`/`next` branching model. See [BRANCHING_STRATEGY.md](BRANCHING_STRATEGY.md) for details.
492+
491493
### Quick Contribution Steps
492494

493495
1. Fork the repository
494-
2. Create a feature branch: `git checkout -b feature/amazing-feature`
496+
2. Create a feature branch from `next`: `git checkout next && git pull && git checkout -b feature/amazing-feature`
495497
3. Make your changes and add tests
496498
4. Run tests: `uv run pytest`
497499
5. Lint code: `uv run ruff check .`
498500
6. Commit with conventional commits: `git commit -m "feat: add amazing feature"`
499-
7. Push and create a Pull Request
501+
7. Push and create a Pull Request **to the `next` branch**
500502

501503
---
502504

‎RECONCILIATION_SUMMARY.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Next Branch Reconciliation - Implementation Summary
2+
3+
## Problem
4+
PR #19 was correctly merged to the `next` branch, but there was confusion about the branching strategy and a need to prevent future direct PRs to `main`.
5+
6+
## Solution Implemented
7+
8+
### 1. Integrated Branch Protection into CI
9+
Modified `.github/workflows/ci.yaml` to include:
10+
- New `check-source-branch` job that runs first on all PRs
11+
- Validates that PRs to `main` come only from `next` branch
12+
- Posts helpful comment explaining the violation
13+
- **Blocks all other CI jobs** if the check fails
14+
15+
### 2. Job Dependency Chain
16+
All CI jobs now depend on `check-source-branch`:
17+
```
18+
check-source-branch (validates branch policy)
19+
↓
20+
lint-dockerfile, test, test-e2e, security
21+
↓
22+
release
23+
↓
24+
generate-sbom, deploy-docs, publish-pypi, publish-testpypi
25+
```
26+
27+
This ensures:
28+
- Invalid PRs fail immediately
29+
- No resources wasted on tests/builds for invalid PRs
30+
- Clear feedback to contributors
31+
32+
### 3. Updated PR Triggers
33+
Updated `ci.yaml` to accept PRs to both `main` and `next`:
34+
```yaml
35+
pull_request:
36+
branches: [ main, next ]
37+
```
38+
39+
### 4. Comprehensive Documentation
40+
Created `BRANCHING_STRATEGY.md` with:
41+
- Complete workflow guide
42+
- Branch purposes and protection rules
43+
- Troubleshooting section
44+
- Benefits of the strategy
45+
46+
## How It Works
47+
48+
### For Valid PRs
49+
```
50+
Feature Branch → next ✅
51+
- check-source-branch: ✅ skipped (not targeting main)
52+
- All other jobs: ✅ run normally
53+
54+
next → main ✅
55+
- check-source-branch: ✅ passed (next to main is allowed)
56+
- All other jobs: ✅ run normally
57+
```
58+
59+
### For Invalid PRs
60+
```
61+
Feature Branch → main ❌
62+
- check-source-branch: ❌ FAILED
63+
- All other jobs: ⏭️ SKIPPED (blocked by failed check)
64+
- Comment posted: Explains how to fix
65+
```
66+
67+
## Key Features
68+
69+
1. **Automated Enforcement**: No manual oversight needed
70+
2. **Fast Feedback**: Fails immediately, no wasted CI time
71+
3. **Helpful Guidance**: Automatic comment explains the issue
72+
4. **Blocking**: All downstream jobs depend on the check
73+
5. **Flexible**: Works for both main and next branches
74+
75+
## Testing
76+
77+
The YAML syntax has been validated. The logic will be tested when:
78+
1. A PR is created from a feature branch to main (should fail)
79+
2. A PR is created from a feature branch to next (should pass)
80+
3. A PR is created from next to main (should pass)
81+
82+
## Next Steps
83+
84+
1. Merge this PR to establish the branching strategy
85+
2. Test by creating a test PR from a feature branch to main
86+
3. Configure GitHub branch protection rules (optional, but recommended)
87+
4. Update team documentation about the workflow
88+
89+
## Files Changed
90+
91+
- `.github/workflows/ci.yaml` - Added check-source-branch job, updated dependencies
92+
- `BRANCHING_STRATEGY.md` - New comprehensive guide
93+
- `RECONCILIATION_SUMMARY.md` - This file
94+
95+
## Benefits
96+
97+
- **Prevents mistakes**: Automatic enforcement before any human sees the PR
98+
- **Saves time**: Invalid PRs fail fast without running expensive tests
99+
- **Clear guidance**: Contributors know exactly what to do
100+
- **No maintenance**: No separate workflow file to maintain

0 commit comments

Comments
 (0)