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

chore(sync): merge main into dev to align branches (#20)

Browse Source 
* fix(ci): add missing PR template enhancements

- Add CI/CD workflow change type
- Expand checklist with quality gates sections
- Add Conventional Commits and branch naming reminders
- Better organize code quality, docs, testing, CI/CD sections

This file was modified in Phase 2 but accidentally not staged.

* docs: add comprehensive CI/CD and branching documentation

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)

* feat(commands): add GitHub workflow integration slash commands

Phase 4: Claude Code Slash Commands

Created 4 GitHub Integration Commands:

1. /github-init - CI/CD system initialization
   - Runs bootstrap workflow
   - Creates dev branch
   - Configures branch protection
   - Sets default branch to dev
   - Complete setup verification

2. /commit-smart - Smart commits with quality gates
   - Pre-commit validation (Python, Bash, secrets)
   - Conventional Commits format generation
   - Interactive commit message builder
   - Quality checks before committing

3. /create-pr - Pull request creation
   - Branch validation
   - Target branch detection (dev/main)
   - PR title generation (Conventional Commits)
   - PR template population
   - Workflow trigger explanation

4. /release - GitHub release creation
   - Version validation (semantic versioning)
   - CHANGELOG.md integration
   - Automated release notes
   - Post-release actions guide

All commands provide:
- Step-by-step guidance
- Copy-paste ready commands
- Validation checks
- Error handling
- Links to documentation

Integration with workflows:
- Commands trigger bootstrap, pr-into-dev, dev-to-main, release workflows
- Enforces quality gates and conventions
- Aligns with branching strategy

Next: Test workflows with sample feature PR

* fix(ci): handle multi-line PR body in linked issues check

Use heredoc to safely write PR body to temp file instead of storing in variable.
This prevents bash from interpreting special characters and multi-line content
as commands (exit code 127 error).

Fixes workflow failure in PR #3.

* fix(ci): skip interactive scripts in bash syntax validation

Interactive scripts that use /dev/tty for user input trigger false positives
in bash -n syntax checking. This change:

- Excludes install.sh from bash validation
- Skips any script containing /dev/tty
- Fixes quality gates failure in PR workflows

Resolves quality gates failure in PR #5.

* release: CI/CD system v1.1.0

* fix(ci): handle multi-line PR body in linked issues check

Use heredoc to safely write PR body to temp file instead of storing in variable.
This prevents bash from interpreting special characters and multi-line content
as commands (exit code 127 error).

Fixes workflow failure in PR #3.

* fix(ci): skip interactive scripts in bash syntax validation

Interactive scripts that use /dev/tty for user input trigger false positives
in bash -n syntax checking. This change:

- Excludes install.sh from bash validation
- Skips any script containing /dev/tty
- Fixes quality gates failure in PR workflows

Resolves quality gates failure in PR #5.

* feat(docs): validate multi-line PR body fix in workflows (#5)

* feat(docs): add CI/CD fix validation documentation

* chore: trigger workflow with updated quality gates

* fix(ci): exclude docs from secret scanning and skip interactive script validation

- Security checks: Exclude docs/ and examples/ from secret pattern matching
  (prevents false positives on documentation examples)
- Install validation: Skip bash -n check for scripts using /dev/tty
  (interactive scripts are valid but fail non-interactive syntax checking)

Fixes workflow failures in dev-to-main PRs.

* fix(ci): skip bash -n check for install.sh in validate workflow

Interactive script with /dev/tty cannot be syntax-checked non-interactively.

* chore(release): merge dev into main - CI fixes and workflow improvements (#16)

* fix(ci): handle multi-line PR body in linked issues check

Use heredoc to safely write PR body to temp file instead of storing in variable.
This prevents bash from interpreting special characters and multi-line content
as commands (exit code 127 error).

Fixes workflow failure in PR #3.

* fix(ci): skip interactive scripts in bash syntax validation

Interactive scripts that use /dev/tty for user input trigger false positives
in bash -n syntax checking. This change:

- Excludes install.sh from bash validation
- Skips any script containing /dev/tty
- Fixes quality gates failure in PR workflows

Resolves quality gates failure in PR #5.

* feat(docs): validate multi-line PR body fix in workflows (#5)

* feat(docs): add CI/CD fix validation documentation

* chore: trigger workflow with updated quality gates

* fix(ci): exclude docs from secret scanning and skip interactive script validation

- Security checks: Exclude docs/ and examples/ from secret pattern matching
  (prevents false positives on documentation examples)
- Install validation: Skip bash -n check for scripts using /dev/tty
  (interactive scripts are valid but fail non-interactive syntax checking)

Fixes workflow failures in dev-to-main PRs.

* fix(ci): skip bash -n check for install.sh in validate workflow

Interactive script with /dev/tty cannot be syntax-checked non-interactively.
This commit is contained in:
Alireza Rezvani
2026-01-07 18:00:46 +01:00
committed by GitHub
parent e684e90e09
commit f52664867d
8 changed files with 2023 additions and 4 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)