justin/ClaudeForge
1
0
Fork 0
mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-03 10:23:15 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: add comprehensive CI/CD and branching documentation

Browse Source 
Phase 3: Documentation & Branch Setup

Created Documentation (1200+ lines):
- GITHUB_WORKFLOWS.md: Complete reference for all 5 workflows and 4 composite actions
  - Detailed explanations of bootstrap, pr-into-dev, dev-to-main, release workflows
  - Quality gates documentation (Python, Markdown, Bash, secrets)
  - Troubleshooting guide for common workflow issues
  - Configuration examples and customization options

- BRANCHING_STRATEGY.md: Standard branching model documentation
  - feature/* → dev → main flow explained
  - Branch protection configuration guide
  - Conventional Commits format with examples
  - Git commands cheat sheet
  - Common scenarios and best practices
  - Merge strategy (squash merges)

Updated README.md:
- Added CI/CD and Quality Gates badges
- Added links to new workflow and branching docs
- Better documentation table organization

Branch Setup:
- Created and pushed dev branch
- Ready for branch protection configuration

Next: Phase 4 (Claude Code slash commands for GitHub workflows)
This commit is contained in:
Reza Rezvani
2025-11-12 13:04:23 +01:00
parent 078bf9f418
commit 60f8926bfe
3 changed files with 1374 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/BRANCHING_STRATEGY.md
+742
View File
@@ -0,0 +1,742 @@
# Branching Strategy
ClaudeForge uses a **Standard Branching Strategy** with protected branches and automated quality gates.
## Overview
```
feature/*, fix/*, hotfix/* → dev → main
↓ ↓ ↓
Development Testing Production
```
**Three permanent branches:**
- `main` - Production-ready code, always deployable
- `dev` - Integration branch for features
- *(temporary)* - Feature, fix, and hotfix branches
**Branch protection:**
- ✅ No direct commits to main or dev
- ✅ All changes via pull requests
- ✅ Automated quality gates required
- ✅ Conventional Commits enforced
- ✅ Linear history (squash merges)
---
## Branch Types
### Main Branch
**Purpose:** Production-ready releases only
**Protection Rules:**
- ✅ Require pull request before merging
- ✅ Require status checks to pass: `quality-gates`, `production-build`
- ✅ Require linear history (squash merges only)
- ✅ No force pushes
- ✅ No deletions
- ✅ Require review from CODEOWNERS
**Who can merge:**
- Only `dev`, `release/*`, or `dependabot/*` branches
- After passing dev-to-main.yml workflow
**Triggers:**
- dev-to-main.yml workflow on PR
- release.yml workflow for GitHub releases
**Typical state:**
- Always matches latest GitHub release
- Only updated when releasing new version
- Every commit corresponds to a version tag (v1.0.0, v1.1.0, etc.)
---
### Dev Branch
**Purpose:** Integration branch for all features
**Protection Rules:**
- ✅ Require pull request before merging
- ✅ Require status checks to pass: `quality-gates`, `validate-pr`
- ✅ Require linear history (squash merges only)
- ✅ No force pushes
- ✅ No deletions
**Who can merge:**
- Feature branches (`feature/*`)
- Fix branches (`fix/*`)
- Hotfix branches (`hotfix/*`)
- Test branches (`test/*`)
- Refactor branches (`refactor/*`)
- Docs branches (`docs/*`)
**Triggers:**
- pr-into-dev.yml workflow on PR
**Typical state:**
- Contains completed features awaiting release
- Ahead of main by several commits
- Reset to main only after release (via merge)
---
### Feature Branches
**Naming Convention:** `feature/<description>`
**Purpose:** New features or enhancements
**Examples:**
- `feature/add-rust-templates`
- `feature/vscode-extension`
- `feature/ai-suggestions`
**Lifecycle:**
1. Create from latest `dev`: `git checkout dev && git pull && git checkout -b feature/my-feature`
2. Make changes, commit with Conventional Commits
3. Push to origin: `git push -u origin feature/my-feature`
4. Create PR to `dev`
5. Pass quality gates and code review
6. Squash merge to `dev`
7. Delete feature branch
**PR Requirements:**
- ✅ Title must follow Conventional Commits: `feat(scope): description`
- ✅ At least one linked issue (recommended)
- ✅ All quality gates pass
- ✅ Code review approved (if CODEOWNERS configured)
---
### Fix Branches
**Naming Convention:** `fix/<description>`
**Purpose:** Bug fixes
**Examples:**
- `fix/installer-windows-path`
- `fix/python-syntax-validation`
- `fix/broken-markdown-links`
**Lifecycle:**
Same as feature branches, but:
- PR title prefix: `fix(scope): description`
- Link to bug issue with `Fixes #123` or `Closes #123`
**PR Requirements:**
- ✅ Title: `fix(scope): description`
- ✅ Linked to bug issue
- ✅ Quality gates pass
- ✅ Test fix if applicable
---
### Hotfix Branches
**Naming Convention:** `hotfix/<description>`
**Purpose:** Urgent fixes for production issues
**Examples:**
- `hotfix/critical-installer-bug`
- `hotfix/security-patch`
**Lifecycle:**
1. Create from `dev`: `git checkout dev && git pull && git checkout -b hotfix/issue-name`
2. Make minimal fix
3. Create PR to `dev`
4. After merge to dev, immediately create PR dev → main
5. Fast-track review and merge
**PR Requirements:**
- ✅ Title: `fix(scope): description` or `hotfix(scope): description`
- ✅ Link to critical issue
- ✅ Quality gates pass (can be expedited)
- ✅ Fast-track review
**Special considerations:**
- Prioritize speed over perfection
- Minimal changes only
- Document reason for hotfix in PR description
---
### Test Branches
**Naming Convention:** `test/<description>`
**Purpose:** Testing experiments or validations
**Examples:**
- `test/new-quality-gate`
- `test/workflow-validation`
**Lifecycle:**
- Same as feature branches
- PR title: `test(scope): description`
- May not require linked issue
---
### Refactor Branches
**Naming Convention:** `refactor/<description>`
**Purpose:** Code improvements without changing functionality
**Examples:**
- `refactor/simplify-analyzer`
- `refactor/improve-error-handling`
**Lifecycle:**
- Same as feature branches
- PR title: `refactor(scope): description`
- Should not change external behavior
---
### Docs Branches
**Naming Convention:** `docs/<description>`
**Purpose:** Documentation-only changes
**Examples:**
- `docs/update-installation-guide`
- `docs/add-troubleshooting-section`
**Lifecycle:**
- Same as feature branches
- PR title: `docs: description` or `docs(scope): description`
- Can skip some quality gates (Python, Bash)
---
## Workflow Diagrams
### Standard Feature Flow
```
Developer's machine:
git checkout dev
git pull origin dev
git checkout -b feature/add-templates
# Make changes
git add .
git commit -m "feat(skill): add Rust template support"
git push -u origin feature/add-templates
GitHub:
Create PR: feature/add-templates → dev
↓
pr-into-dev.yml runs:
├─ Branch name validation ✅
├─ PR title validation ✅
├─ Linked issue check ⚠️
├─ Quality gates ✅
└─ Ready for review
Code review + approval
↓
Squash and merge to dev
↓
Delete feature branch
```
### Release Flow
```
Dev branch ready for release:
├─ All features merged
├─ CHANGELOG.md updated
└─ Version bumped
GitHub:
Create PR: dev → main
↓
dev-to-main.yml runs:
├─ Source branch validation ✅ (dev allowed)
├─ CHANGELOG.md check ✅
├─ Version consistency ✅
├─ Quality gates ✅
├─ Production build validation ✅
└─ Ready for production
Approval + merge to main
↓
Run release.yml workflow:
├─ Input version: 1.1.0
├─ Validate version format ✅
├─ Extract CHANGELOG notes ✅
├─ Create GitHub release ✅
└─ Tag created: v1.1.0
Result:
├─ main branch updated
├─ GitHub release published
├─ Installable via one-line command
└─ Ready for announcements
```
### Hotfix Flow
```
Critical production bug discovered:
Developer's machine:
git checkout dev
git pull origin dev
git checkout -b hotfix/critical-installer-bug
# Make minimal fix
git commit -m "fix(installer): resolve critical Windows path issue"
git push -u origin hotfix/critical-installer-bug
GitHub:
Create PR: hotfix/critical-installer-bug → dev
↓
pr-into-dev.yml runs (expedited review)
↓
Merge to dev
↓
Immediately create PR: dev → main
↓
dev-to-main.yml runs (fast-track)
↓
Merge to main
↓
Create hotfix release: v1.0.1
```
---
## Branch Protection Configuration
### Configure Main Branch Protection
1. Go to Settings → Branches → Add rule
2. Branch name pattern: `main`
3. Enable:
- ✅ Require a pull request before merging
- ✅ Require approvals: 1 (if team)
- ✅ Dismiss stale reviews
- ✅ Require review from Code Owners
- ✅ Require status checks to pass before merging
- ✅ Require branches to be up to date
- Add required checks:
- `quality-gates`
- `production-build`
- `validate-release-pr`
- ✅ Require conversation resolution before merging
- ✅ Require linear history
- ✅ Do not allow bypassing the above settings
4. Under "Rules applied to everyone including administrators":
- ✅ Restrict deletions
- ✅ Block force pushes
5. Save changes
### Configure Dev Branch Protection
1. Go to Settings → Branches → Add rule
2. Branch name pattern: `dev`
3. Enable:
- ✅ Require a pull request before merging
- Require approvals: 0 (can be 1 if team)
- ✅ Require status checks to pass before merging
- Add required checks:
- `quality-gates`
- `validate-pr`
- ✅ Require linear history
- ✅ Do not allow bypassing the above settings
4. Under "Rules applied to everyone including administrators":
- ✅ Restrict deletions
- ✅ Block force pushes
5. Save changes
---
## Commit Message Guidelines
ClaudeForge uses **Conventional Commits** format.
### Format
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Type (Required)
- `feat` - New feature
- `fix` - Bug fix
- `docs` - Documentation only
- `style` - Code style (formatting, semicolons)
- `refactor` - Code change (neither fix nor feature)
- `perf` - Performance improvement
- `test` - Add/update tests
- `build` - Build system or dependencies
- `ci` - CI/CD configuration
- `chore` - Other changes (no src/test changes)
- `revert` - Revert previous commit
### Scope (Optional but Recommended)
- `installer` - Installation scripts
- `skill` - Python skill modules
- `command` - Slash commands
- `agent` - Guardian agent
- `docs` - Documentation
- `ci` - CI/CD workflows
- `workflows` - GitHub Actions
### Subject (Required)
- Use imperative mood: "add" not "added" or "adds"
- Don't capitalize first letter
- No period at the end
- Maximum 50 characters
### Body (Optional)
- Explain what and why vs. how
- Wrap at 72 characters
- Separate from subject with blank line
### Footer (Optional)
- Reference issues: `Closes #123`, `Fixes #456`
- Breaking changes: `BREAKING CHANGE: description`
### Examples
**Good:**
```
feat(installer): add Windows PowerShell support
Add install.ps1 script for Windows users with equivalent
functionality to install.sh bash script.
Closes #42
```
**Good:**
```
fix(skill): correct template selection logic
Fix bug where wrong template was selected for TypeScript
projects. The analyzer was not correctly detecting tsconfig.json.
Fixes #156
```
**Good:**
```
docs: update installation troubleshooting guide
Add common installation issues based on user feedback
from issues #78, #82, and #91.
```
**Bad:**
```
Added new feature
```
- Missing type and scope
- Wrong tense (should be "add")
- Vague subject
**Bad:**
```
fix: Fixed the bug
```
- Capitalized subject
- Unnecessary word "the"
- No details on what bug
---
## PR Title Requirements
PR titles MUST follow Conventional Commits format.
**Valid examples:**
- `feat(installer): add Windows PowerShell support`
- `fix(skill): correct Python syntax validation`
- `docs: update installation guide`
- `refactor(analyzer): simplify project detection`
- `ci: add Python dependency updates to dependabot`
**Invalid examples:**
- `Add new feature` ❌ Missing type/scope
- `Fixed bug` ❌ Wrong tense, no scope
- `Update docs` ❌ Missing colon
- `FEAT: Add feature` ❌ Uppercase type
- `feat: Add feature.` ❌ Period at end
**Validation:**
- pr-into-dev.yml workflow validates PR title format
- Fails if format is incorrect
- Auto-comments with fix instructions
---
## Merge Strategies
ClaudeForge uses **Squash and Merge** exclusively.
### Why Squash?
✅ **Linear history** - Easy to understand and navigate
✅ **Clean log** - One commit per feature/fix
✅ **Easy revert** - Revert entire feature with one command
✅ **Better releases** - Clear association between features and versions
### How it Works
When merging PR with multiple commits:
**Before merge (feature branch):**
```
feat: add template A
fix: correct typo
feat: add template B
refactor: simplify code
test: add unit tests
```
**After merge (dev branch):**
```
feat(skill): add Rust templates (#42)
- Add Rust template A
- Add Rust template B
- Simplify template selection
- Add unit tests
Co-authored-by: Developer <dev@example.com>
```
### Merge Commit Message
Automatically generated:
- **Title:** From PR title (Conventional Commits format)
- **Body:** From PR description
- **Footer:** PR number, co-authors
---
## Git Commands Cheat Sheet
### Start New Feature
```bash
# Update dev
git checkout dev
git pull origin dev
# Create feature branch
git checkout -b feature/my-feature
# Make changes and commit
git add .
git commit -m "feat(scope): add feature"
# Push to GitHub
git push -u origin feature/my-feature
```
### Update Feature Branch with Latest Dev
```bash
# While on feature branch
git checkout dev
git pull origin dev
git checkout feature/my-feature
git rebase dev
# If conflicts, resolve and continue
git rebase --continue
# Force push (rebase rewrites history)
git push --force-with-lease origin feature/my-feature
```
### Sync Fork (if contributing from fork)
```bash
# Add upstream remote (once)
git remote add upstream https://github.com/alirezarezvani/ClaudeForge.git
# Update from upstream
git fetch upstream
git checkout dev
git merge upstream/dev
git push origin dev
```
### Rename Branch
```bash
# Rename current branch
git branch -m new-branch-name
# Push with new name
git push -u origin new-branch-name
# Delete old branch on remote
git push origin --delete old-branch-name
```
### Delete Merged Branches
```bash
# Delete local branch after merge
git branch -d feature/my-feature
# Delete remote branch
git push origin --delete feature/my-feature
# Prune deleted remote branches
git fetch --prune
```
---
## Common Scenarios
### Scenario 1: Feature PR Rejected by Workflow
**Problem:** PR validation fails with "Invalid branch name"
**Solution:**
```bash
# Rename branch
git branch -m feature/correct-name
# Force push
git push --force-with-lease origin feature/correct-name
# Update PR with new branch
```
### Scenario 2: Need to Update PR Title
**Problem:** PR title doesn't follow Conventional Commits
**Solution:**
1. Go to PR page on GitHub
2. Click "Edit" next to PR title
3. Update to format: `type(scope): description`
4. Save
5. Workflow re-runs automatically
### Scenario 3: Forgot to Update CHANGELOG.md
**Problem:** dev-to-main warns CHANGELOG.md not updated
**Solution:**
```bash
# On dev branch
git checkout dev
git pull origin dev
# Edit CHANGELOG.md
# Add version entry under [Unreleased] or create new [1.1.0] section
git add CHANGELOG.md
git commit -m "docs: update CHANGELOG for v1.1.0"
git push origin dev
# PR to main will now pass CHANGELOG check
```
### Scenario 4: Emergency Hotfix Needed
**Problem:** Critical bug in production (main)
**Solution:**
```bash
# Create hotfix from dev (not main)
git checkout dev
git pull origin dev
git checkout -b hotfix/critical-bug
# Make minimal fix
git add .
git commit -m "fix(installer): resolve critical security issue"
git push -u origin hotfix/critical-bug
# Create PR to dev, get fast-track approval
# After merge to dev, immediately create PR dev → main
# After merge to main, create hotfix release v1.0.1
```
### Scenario 5: Multiple Features in Development
**Problem:** Need to work on feature B while feature A is in review
**Solution:**
```bash
# Feature A already in PR
git checkout dev
git pull origin dev
# Start feature B from latest dev
git checkout -b feature/feature-b
# Work independently
# Both PRs can be reviewed in parallel
# Merge order doesn't matter (both target dev)
```
---
## Best Practices
### ✅ Do
- ✅ Create descriptive branch names
- ✅ Follow Conventional Commits format
- ✅ Link issues in PR description
- ✅ Update CHANGELOG.md for releases
- ✅ Keep feature branches short-lived (< 1 week)
- ✅ Sync with dev frequently
- ✅ Write clear commit messages
- ✅ Test locally before pushing
- ✅ Respond to review comments
- ✅ Delete merged branches
### ❌ Don't
- ❌ Commit directly to main or dev
- ❌ Force push to main or dev
- ❌ Merge without quality gates passing
- ❌ Use vague commit messages
- ❌ Include unrelated changes in PR
- ❌ Commit secrets or sensitive data
- ❌ Leave stale branches unmerged
- ❌ Skip code review
- ❌ Bypass branch protection (even admins)
- ❌ Merge without linked issue (for features/fixes)
---
## Related Documentation
- [GITHUB_WORKFLOWS.md](./GITHUB_WORKFLOWS.md) - Workflow details and automation
- [CONTRIBUTING.md](./CONTRIBUTING.md) - How to contribute
- [CHANGELOG.md](../CHANGELOG.md) - Version history
---
## Questions?
**Issues:** Report at [GitHub Issues](https://github.com/alirezarezvani/ClaudeForge/issues)
**Discussions:** Ask in [GitHub Discussions](https://github.com/alirezarezvani/ClaudeForge/discussions)
docs/GITHUB_WORKFLOWS.md
+628
View File
@@ -0,0 +1,628 @@
# GitHub Workflows Reference
Complete guide to ClaudeForge's CI/CD automation system.
## Overview
ClaudeForge uses GitHub Actions for automated quality validation, release management, and repository setup. The system is built with:
- **4 Composite Actions** - Reusable components (DRY principle)
- **5 Workflows** - Automated pipelines for different scenarios
- **Standard Branching** - feature/* → dev → main flow
- **Quality Gates** - Python, Markdown, Bash, secret validation
---
## Composite Actions
Reusable building blocks used across workflows.
### 1. setup-python-deps
**Location:** `.github/actions/setup-python-deps/`
**Purpose:** Sets up Python with dependency caching for 90%+ faster workflow runs.
**Inputs:**
- `python-version` (optional, default: `3.11`) - Python version to install
**Outputs:**
- `cache-hit` - Whether the cache was hit (true/false)
- `python-version` - Python version that was installed
**What it does:**
1. Installs specified Python version
2. Caches pip dependencies based on requirements.txt
3. Installs validation tools (flake8, pylint, black, mypy)
4. Installs project dependencies if requirements.txt exists
**Usage in workflows:**
```yaml
- name: Setup Python
uses: ./.github/actions/setup-python-deps
with:
python-version: '3.11'
```
---
### 2. fork-safety
**Location:** `.github/actions/fork-safety/`
**Purpose:** Detects fork PRs and prevents malicious write operations.
**Inputs:**
- `github-token` (optional, default: `${{ github.token }}`) - GitHub token
**Outputs:**
- `is-fork` - Whether this is a fork PR (true/false)
- `should-skip-writes` - Whether to skip write operations (true/false)
- `source-repo` - Full name of source repository
- `base-repo` - Full name of base repository
**Security Features:**
- Automatically detects forked pull requests
- Prevents issue updates, labels, and comments from forks
- Protects against malicious actions in fork workflows
**Usage in workflows:**
```yaml
- name: Check fork status
id: fork-check
uses: ./.github/actions/fork-safety
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
- name: Update issue (skip if fork)
if: steps.fork-check.outputs.should-skip-writes != 'true'
run: gh issue comment ${{ github.event.number }} --body "Updated"
```
---
### 3. rate-limit-check
**Location:** `.github/actions/rate-limit-check/`
**Purpose:** Circuit breaker pattern to prevent GitHub API exhaustion.
**Inputs:**
- `github-token` (required) - GitHub token for API access
- `minimum-remaining` (optional, default: `50`) - Minimum calls required to proceed
- `fail-on-limit` (optional, default: `false`) - Fail workflow if below threshold
**Outputs:**
- `can-proceed` - Whether enough API calls remain (true/false)
- `remaining` - Number of API calls remaining
- `limit` - Total API rate limit
- `used` - Number of API calls used
- `reset-time` - Unix timestamp when limit resets
- `reset-time-human` - Human-readable reset time
**What it does:**
1. Queries GitHub API rate limit status
2. Checks if remaining calls exceed minimum threshold
3. Warns or fails if rate limit too low
4. Displays usage statistics and reset time
**Usage in workflows:**
```yaml
- name: Check API rate limit
uses: ./.github/actions/rate-limit-check
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
minimum-remaining: 100
fail-on-limit: false
```
---
### 4. quality-gates
**Location:** `.github/actions/quality-gates/`
**Purpose:** Comprehensive quality validation for Python, Markdown, Bash, and secrets.
**Inputs:**
- `python-version` (optional, default: `3.11`) - Python version to use
- `skip-python` (optional, default: `false`) - Skip Python validation
- `skip-markdown` (optional, default: `false`) - Skip Markdown validation
- `skip-bash` (optional, default: `false`) - Skip Bash validation
- `skip-secrets` (optional, default: `false`) - Skip secret scanning
**Outputs:**
- `python-passed` - Whether Python validation passed
- `markdown-passed` - Whether Markdown validation passed
- `bash-passed` - Whether Bash validation passed
- `secrets-passed` - Whether secret scanning passed
- `all-passed` - Whether all gates passed
**Quality Checks:**
**Python Validation:**
- Syntax errors (flake8 E9, F63, F7, F82)
- Code style warnings (complexity, line length)
- Validates all `*.py` files in skill/ directory
**Markdown Validation:**
- Empty file detection
- Broken internal link detection
- Validates all `*.md` files (excluding node_modules, .git)
**Bash Validation:**
- Syntax checking with `bash -n`
- Validates all `*.sh` files
**Secret Scanning:**
- Detects patterns: api_key, api_secret, password, token, AWS keys, GITHUB_TOKEN
- Checks for committed .env files
- Filters out false positives (examples, templates)
**Usage in workflows:**
```yaml
- name: Run quality gates
uses: ./.github/actions/quality-gates
with:
python-version: '3.11'
skip-python: false
skip-secrets: false
```
---
## Workflows
### 1. Bootstrap Repository
**File:** `.github/workflows/bootstrap.yml`
**Trigger:** Manual (workflow_dispatch)
**Purpose:** One-time repository setup for labels, milestones, and settings validation.
**Inputs:**
- `create-labels` (boolean, default: true) - Create standard labels
- `create-milestones` (boolean, default: true) - Create initial milestones
- `validate-settings` (boolean, default: true) - Validate repository settings
**What it creates:**
**Labels (23 total):**
- **Type:** bug, enhancement, documentation, refactor, performance, security, test
- **Priority:** critical, high, medium, low
- **Status:** blocked, in progress, review needed, needs discussion
- **Component:** installer, skill, command, agent, docs, ci/cd
- **Other:** good first issue, help wanted, dependencies, breaking change
**Milestones (3 total):**
- v1.1.0 (due: +1 month) - Additional templates, enhanced detection
- v1.2.0 (due: +2 months) - VS Code extension, advanced hooks
- v2.0.0 (due: +4 months) - AI suggestions, multi-language, dashboard
**Settings Validation:**
- Checks if Issues, Wiki, Discussions are enabled
- Validates default branch configuration
- Provides recommendations if settings are non-optimal
**How to run:**
1. Go to Actions → Bootstrap Repository
2. Click "Run workflow"
3. Select options (all enabled by default)
4. Click "Run workflow"
**When to run:**
- Once after initial repository setup
- After cloning to a new repository
- To recreate deleted labels/milestones
---
### 2. Reusable PR Checks
**File:** `.github/workflows/reusable-pr-checks.yml`
**Trigger:** Called by other workflows (workflow_call)
**Purpose:** DRY quality gate orchestrator for pull request validation.
**Inputs:**
- `python-version` (string, default: '3.11')
- `skip-python` (boolean, default: false)
- `skip-markdown` (boolean, default: false)
- `skip-bash` (boolean, default: false)
- `skip-secrets` (boolean, default: false)
**What it does:**
1. Checks out code
2. Runs fork safety check
3. Checks GitHub API rate limit
4. Executes all quality gates
5. Generates summary report
6. Fails if any quality gate fails
**Quality Gates:**
- ✅ Python syntax (flake8)
- ✅ Markdown linting
- ✅ Bash script validation
- ✅ Secret scanning
**Called by:**
- pr-into-dev.yml (feature PRs)
- dev-to-main.yml (release PRs)
**Not called directly** - Use pr-into-dev or dev-to-main workflows instead.
---
### 3. PR into Dev
**File:** `.github/workflows/pr-into-dev.yml`
**Trigger:** Pull request to `dev` branch (opened, reopened, synchronize, ready_for_review)
**Purpose:** Validate feature/fix pull requests before merging to dev.
**Validation Steps:**
**1. PR Structure Validation:**
- ✅ **Branch name** must start with: `feature/`, `fix/`, `hotfix/`, `test/`, `refactor/`, `docs/`
- ✅ **PR title** must follow Conventional Commits format:
- Format: `type(scope): subject`
- Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
- Example: `feat(installer): add Windows PowerShell support`
- ✅ **Linked issues** - PR body should reference at least one issue (warning if missing)
- Keywords: Closes, Fixes, Resolves, Relates to, Ref, References
**2. Quality Checks:**
- Calls reusable-pr-checks.yml
- Runs all quality gates (Python, Markdown, Bash, secrets)
**Auto-comments on failure:**
If validation fails, bot comments with:
- What failed (branch name, PR title)
- How to fix (examples, instructions)
- Link to CONTRIBUTING.md
**Example flow:**
```
Developer creates PR: feature/add-rust-templates → dev
↓
Workflow runs:
1. ✅ Branch name valid (starts with feature/)
2. ❌ PR title invalid (missing conventional format)
3. Bot comments with fix instructions
↓
Developer updates PR title: "feat(skill): add Rust template support"
↓
Workflow re-runs:
1. ✅ Branch name valid
2. ✅ PR title valid
3. ✅ Quality gates pass
↓
PR ready for review!
```
---
### 4. Dev to Main (Release Gate)
**File:** `.github/workflows/dev-to-main.yml`
**Trigger:** Pull request to `main` branch (opened, reopened, synchronize, ready_for_review)
**Purpose:** Production release gate with strict validation.
**Validation Steps:**
**1. Source Branch Validation:**
- ✅ **Only allowed branches:**
- `dev` (standard release flow)
- `release/*` (release branches)
- `dependabot/*` (dependency updates)
- ❌ **NOT allowed:**
- `feature/*`, `fix/*`, `test/*` - Must merge to dev first
**Auto-comments if invalid branch:**
- Explains which branches can merge to main
- Provides step-by-step fix instructions
- Links to BRANCHING_STRATEGY.md
**2. CHANGELOG.md Check:**
- Checks if CHANGELOG.md was updated in this PR
- Warns if not updated (doesn't fail)
- Recommends adding release notes
**3. Version Consistency:**
- Checks version in CHANGELOG.md
- Checks version references in install.sh/install.ps1
- Warns on version mismatches
**4. Quality Checks:**
- Calls reusable-pr-checks.yml
- Full quality gate validation
**5. Production Build Validation:**
- ✅ install.sh exists and is executable
- ✅ install.ps1 exists
- ✅ All skill modules exist (5 files)
- ✅ Core documentation exists
**Example flow:**
```
Feature branch tries to merge to main:
↓
❌ Workflow fails:
- feature/new-feature is not allowed
- Must merge to dev first
- Bot comments with instructions
↓
Correct flow:
1. feature/new-feature → dev (PR approved and merged)
2. dev → main (PR created)
↓
✅ Workflow passes:
- dev branch allowed
- CHANGELOG.md updated
- Quality gates pass
- Production build valid
↓
Ready for production!
```
---
### 5. Create Release
**File:** `.github/workflows/release.yml`
**Trigger:** Manual (workflow_dispatch)
**Purpose:** Create GitHub releases with automated release notes.
**Inputs:**
- `version` (required) - Release version (e.g., 1.1.0)
- `prerelease` (boolean, default: false) - Mark as pre-release
- `draft` (boolean, default: false) - Create as draft
**Validation:**
1. ✅ Version format (semantic versioning: X.Y.Z or X.Y.Z-beta.1)
2. ✅ Tag doesn't already exist (v1.1.0)
3. ✅ CHANGELOG.md contains version entry (warning if missing)
**Release Notes Generation:**
1. Extracts notes from CHANGELOG.md for the version
2. Adds installation instructions (one-line install + manual)
3. Lists all commits since last release
4. Includes full changelog link
**Example release notes:**
```markdown
Release v1.1.0
[Content from CHANGELOG.md for v1.1.0]
---
## 📦 Installation
### One-Line Install (Recommended)
```bash
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash
```
### Manual Install
```bash
wget https://github.com/alirezarezvani/ClaudeForge/archive/refs/tags/v1.1.0.tar.gz
tar -xzf v1.1.0.tar.gz
cd ClaudeForge-1.1.0
./install.sh
```
📚 **Documentation**: https://github.com/alirezarezvani/ClaudeForge/blob/main/docs/INSTALLATION.md
## 📝 Commits
- feat(skill): add Rust template support (a1b2c3d)
- fix(installer): correct Windows path handling (e4f5g6h)
...
---
**Full Changelog**: https://github.com/alirezarezvani/ClaudeForge/blob/main/CHANGELOG.md
```
**How to create a release:**
**Option 1: GitHub UI**
1. Go to Actions → Create Release
2. Click "Run workflow"
3. Enter version (e.g., 1.1.0)
4. Select prerelease/draft if needed
5. Click "Run workflow"
**Option 2: `/release` command** (Phase 4)
- Run `/release` slash command in Claude Code
- Follow interactive prompts
**After release created:**
1. GitHub release published with auto-generated notes
2. Git tag created (v1.1.0)
3. Installable via one-line command
4. Consider:
- Announcing in Discussions
- Updating README.md badges
- Sharing on social media
---
## Workflow Execution Order
**Full Development Lifecycle:**
```
1. Bootstrap (once)
└─ Creates labels, milestones, validates settings
2. Feature Development
├─ Developer creates feature/add-templates branch
├─ Makes changes, commits
└─ Creates PR: feature/add-templates → dev
3. PR into Dev
├─ pr-into-dev.yml runs
├─ Validates branch name, PR title, linked issues
├─ Calls reusable-pr-checks.yml
├─ quality-gates validates Python, Markdown, Bash, secrets
└─ ✅ Passes → Ready for review
4. Merge to Dev
└─ Feature merged to dev branch
5. Release to Main
├─ Create PR: dev → main
├─ dev-to-main.yml runs
├─ Validates source branch (dev allowed)
├─ Checks CHANGELOG.md updated
├─ Validates production build
├─ Calls reusable-pr-checks.yml
└─ ✅ Passes → Ready for production
6. Create Release
├─ Run release.yml workflow
├─ Input version: 1.1.0
├─ Validates version format, tag availability
├─ Extracts release notes from CHANGELOG.md
├─ Creates GitHub release with notes
└─ ✅ Release published!
```
---
## Quality Gates Summary
All PRs (dev and main) must pass these gates:
| Gate | Check | Tool | Fail Condition |
|------|-------|------|----------------|
| Python Syntax | Syntax errors, style violations | flake8 | Syntax error found |
| Markdown Lint | Empty files, broken links | grep | N/A (warnings only) |
| Bash Scripts | Shell syntax | bash -n | Syntax error found |
| Secret Scan | Hardcoded secrets, .env files | grep patterns | .env file committed |
| Branch Name | Convention (feature/*, fix/*) | bash regex | Invalid prefix |
| PR Title | Conventional Commits format | bash regex | Invalid format |
| Linked Issue | References issue with keywords | grep | Warning only |
| Source Branch | Allowed for main (dev, release/*) | bash | Invalid branch |
---
## Troubleshooting
### Workflow fails with "rate limit exceeded"
**Cause:** Too many GitHub API calls in short time
**Fix:**
1. Wait for rate limit reset (shown in logs)
2. Re-run workflow after reset time
3. If persistent, increase `minimum-remaining` in rate-limit-check
### Python validation fails but code is correct
**Cause:** flake8 is strict about style
**Fix:**
1. Check logs for specific errors
2. Run `flake8 skill/` locally to see issues
3. Fix style issues or add `# noqa` comments for exceptions
### Secret scanning detects false positive
**Cause:** Word "password" or "token" in documentation
**Fix:**
1. Check the pattern detected
2. If it's documentation/example, it's safe (warning only)
3. Real secrets will fail the workflow
### Fork PR can't update issues
**Expected behavior:** Fork PRs are restricted for security
**Explanation:**
- Fork PRs run in read-only mode
- Issue updates, labels, comments are skipped
- This prevents malicious actions from forks
- Maintainer can manually update after review
### Branch validation rejects my PR
**Cause:** Branch name doesn't match convention
**Fix:**
1. Rename branch: `git branch -m feature/my-feature`
2. Force push: `git push -f origin feature/my-feature`
3. Update PR with new branch name
### PR title validation fails
**Cause:** Title doesn't follow Conventional Commits
**Fix:**
Update PR title to format: `type(scope): subject`
Examples:
- `feat(installer): add Windows support`
- `fix(skill): correct template selection`
- `docs: update installation guide`
---
## Configuration
### Customizing Quality Gates
To skip specific checks, modify workflow inputs in `pr-into-dev.yml` or `dev-to-main.yml`:
```yaml
quality-checks:
uses: ./.github/workflows/reusable-pr-checks.yml
with:
skip-python: false # Set to true to skip Python validation
skip-markdown: false # Set to true to skip Markdown linting
skip-bash: false # Set to true to skip Bash validation
skip-secrets: false # Set to true to skip secret scanning
```
### Adjusting Rate Limit Threshold
In workflows using rate-limit-check, adjust `minimum-remaining`:
```yaml
- name: Rate limit check
uses: ./.github/actions/rate-limit-check
with:
minimum-remaining: 100 # Increase if workflow uses many API calls
fail-on-limit: false # Set to true to fail instead of warn
```
### Adding Custom Labels
Edit `bootstrap.yml` to add more labels:
```yaml
gh label create "custom-label" --description "Description" --color "hex-color" --force
```
---
## Related Documentation
- [BRANCHING_STRATEGY.md](./BRANCHING_STRATEGY.md) - Branch flow and protection rules
- [CONTRIBUTING.md](./CONTRIBUTING.md) - How to contribute with PR process
- [INSTALLATION.md](./INSTALLATION.md) - User installation guide
- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) - Common issues and solutions
---
## Support
**Issues:** Report bugs or request features at [GitHub Issues](https://github.com/alirezarezvani/ClaudeForge/issues)
**Discussions:** Ask questions in [GitHub Discussions](https://github.com/alirezarezvani/ClaudeForge/discussions)
**Documentation:** Full docs at [docs/](../docs/)