personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(plugins): implement Sprint 5 documentation and fixes (#266-#269)

Browse Source 
Release v5.2.0

Documentation:
- Add git-flow branching strategy guide (docs/BRANCHING-STRATEGY.md)
- Add clarity-assist ND support documentation (docs/ND-SUPPORT.md)
- Update DEBUGGING-CHECKLIST.md with Gitea auto-close behavior and MCP restart notes
- Update plugin READMEs to reference new documentation

Bug Fix:
- Add milestone parameter to update_issue MCP tool (gitea_client.py, server.py, tools/issues.py)

Version Updates:
- Marketplace version: 5.1.0 → 5.2.0
- README title: v5.1.0 → v5.2.0
- CHANGELOG: [Unreleased] → [5.2.0] - 2026-01-28

Closes #266, Closes #267, Closes #268, Closes #269

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-28 14:24:08 -05:00
parent f6d9fcaae2
commit baad41da98
11 changed files with 967 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
plugins/git-flow/README.md
View File

@@ -119,6 +119,10 @@ The git-assistant agent helps resolve merge conflicts with analysis and recommen
→ Status: Clean, up-to-date
```
## Documentation
- [Branching Strategy Guide](docs/BRANCHING-STRATEGY.md) - Detailed documentation of the `development -> staging -> main` promotion flow
## Integration
For CLAUDE.md integration instructions, see `claude-md-integration.md`.

541
plugins/git-flow/docs/BRANCHING-STRATEGY.md Normal file
View File

@@ -0,0 +1,541 @@
# Branching Strategy
## Overview
This document defines the branching strategy used by git-flow to manage code changes across environments. The strategy ensures:
- **Stability**: Production code is always release-ready
- **Isolation**: Features are developed in isolation without affecting others
- **Traceability**: Clear history of what changed and when
- **Collaboration**: Multiple developers can work simultaneously without conflicts
The strategy follows a hierarchical promotion model: feature branches merge into development, which promotes to staging for testing, and finally to main for production release.
## Branch Types
### Main Branches
| Branch | Purpose | Stability | Direct Commits |
|--------|---------|-----------|----------------|
| `main` | Production releases | Highest | Never |
| `staging` | Pre-production testing | High | Never |
| `development` | Active development | Medium | Never |
### Feature Branches
Feature branches are short-lived branches created from `development` for implementing specific changes.
| Prefix | Purpose | Example |
|--------|---------|---------|
| `feat/` | New features | `feat/user-authentication` |
| `fix/` | Bug fixes | `fix/login-timeout-error` |
| `docs/` | Documentation only | `docs/api-reference` |
| `refactor/` | Code restructuring | `refactor/auth-module` |
| `test/` | Test additions/fixes | `test/auth-coverage` |
| `chore/` | Maintenance tasks | `chore/update-dependencies` |
### Special Branches
| Branch | Purpose | Created From | Merges Into |
|--------|---------|--------------|-------------|
| `hotfix/*` | Emergency production fixes | `main` | `main` AND `development` |
| `release/*` | Release preparation | `development` | `staging` then `main` |
## Branch Hierarchy
```
PRODUCTION
│
▼
┌───────────────[ main ]───────────────┐
│ (stable releases) │
│ ▲ │
│ │ PR │
│ │ │
│ ┌───────┴───────┐ │
│ │ staging │ │
│ │ (testing) │ │
│ └───────▲───────┘ │
│ │ PR │
│ │ │
│ ┌─────────┴─────────┐ │
│ │ development │ │
│ │ (integration) │ │
│ └─────────▲─────────┘ │
│ ╱ │ ╲ │
│ PR╱ │PR ╲PR │
│ ╱ │ ╲ │
│ ┌─────┴──┐ ┌──┴───┐ ┌┴─────┐ │
│ │ feat/* │ │ fix/*│ │docs/*│ │
│ └────────┘ └──────┘ └──────┘ │
│ FEATURE BRANCHES │
└───────────────────────────────────────┘
```
## Workflow
### Feature Development
The standard workflow for implementing a new feature or fix:
```mermaid
gitGraph
commit id: "initial"
branch development
checkout development
commit id: "dev-base"
branch feat/new-feature
checkout feat/new-feature
commit id: "implement"
commit id: "tests"
commit id: "polish"
checkout development
merge feat/new-feature id: "PR merged"
commit id: "other-work"
```
**Steps:**
1. **Create branch from development**
```bash
git checkout development
git pull origin development
git checkout -b feat/add-user-auth
```
Or use git-flow command:
```
/branch-start add user authentication
```
2. **Implement changes**
- Make commits following conventional commit format
- Keep commits atomic and focused
- Push regularly to remote
3. **Create Pull Request**
- Target: `development`
- Include description of changes
- Link related issues
4. **Review and merge**
- Address review feedback
- Squash or rebase as needed
- Merge when approved
5. **Cleanup**
- Delete feature branch after merge
```
/branch-cleanup
```
### Release Promotion
Promoting code from development to production:
```mermaid
gitGraph
commit id: "v1.0.0" tag: "v1.0.0"
branch development
checkout development
commit id: "feat-1"
commit id: "feat-2"
commit id: "fix-1"
branch staging
checkout staging
commit id: "staging-test"
checkout main
merge staging id: "v1.1.0" tag: "v1.1.0"
checkout development
merge main id: "sync"
```
**Steps:**
1. **Prepare release**
- Ensure development is stable
- Update version numbers
- Update CHANGELOG.md
2. **Promote to staging**
```bash
git checkout staging
git merge development
git push origin staging
```
3. **Test in staging**
- Run integration tests
- Perform QA validation
- Fix any issues (merge fixes to development first, then re-promote)
4. **Promote to main**
```bash
git checkout main
git merge staging
git tag -a v1.1.0 -m "Release v1.1.0"
git push origin main --tags
```
5. **Sync development**
```bash
git checkout development
git merge main
git push origin development
```
### Hotfix Handling
Emergency fixes for production issues:
```mermaid
gitGraph
commit id: "v1.0.0" tag: "v1.0.0"
branch development
checkout development
commit id: "ongoing-work"
checkout main
branch hotfix/critical-bug
checkout hotfix/critical-bug
commit id: "fix"
checkout main
merge hotfix/critical-bug id: "v1.0.1" tag: "v1.0.1"
checkout development
merge main id: "sync-fix"
```
**Steps:**
1. **Create hotfix branch from main**
```bash
git checkout main
git pull origin main
git checkout -b hotfix/critical-security-fix
```
2. **Implement fix**
- Minimal, focused changes only
- Include tests for the fix
- Follow conventional commit format
3. **Merge to main**
```bash
git checkout main
git merge hotfix/critical-security-fix
git tag -a v1.0.1 -m "Hotfix: critical security fix"
git push origin main --tags
```
4. **Merge to development** (critical step)
```bash
git checkout development
git merge main
git push origin development
```
5. **Delete hotfix branch**
```bash
git branch -d hotfix/critical-security-fix
git push origin --delete hotfix/critical-security-fix
```
## PR Requirements
### To development
| Requirement | Description |
|-------------|-------------|
| Passing tests | All CI tests must pass |
| Conventional commit | Message follows `type(scope): description` format |
| No conflicts | Branch must be rebased on latest development |
| Code review | At least one approval (recommended) |
### To staging
| Requirement | Description |
|-------------|-------------|
| All checks pass | CI, linting, tests, security scans |
| From development | Only PRs from development branch |
| Clean history | Squashed or rebased commits |
| Release notes | CHANGELOG updated with version |
### To main (Protected)
| Requirement | Description |
|-------------|-------------|
| Source restriction | PRs only from `staging` or `development` |
| All checks pass | Complete CI pipeline success |
| Approvals | Minimum 1-2 reviewer approvals |
| No direct push | Force push disabled |
| Version tag | Must include version tag on merge |
## Branch Flow Diagram
### Complete Lifecycle
```mermaid
flowchart TD
subgraph Feature["Feature Development"]
A[Create feature branch] --> B[Implement changes]
B --> C[Push commits]
C --> D[Create PR to development]
D --> E{Review passed?}
E -->|No| B
E -->|Yes| F[Merge to development]
F --> G[Delete feature branch]
end
subgraph Release["Release Cycle"]
H[development stable] --> I[Create PR to staging]
I --> J[Test in staging]
J --> K{Tests passed?}
K -->|No| L[Fix in development]
L --> H
K -->|Yes| M[Create PR to main]
M --> N[Tag release]
N --> O[Sync development]
end
subgraph Hotfix["Hotfix Process"]
P[Critical bug in prod] --> Q[Create hotfix from main]
Q --> R[Implement fix]
R --> S[Merge to main + tag]
S --> T[Merge to development]
end
G --> H
O --> Feature
T --> Feature
```
### Release Cycle Timeline
```mermaid
gantt
title Release Cycle
dateFormat YYYY-MM-DD
section Feature Development
Feature A :a1, 2024-01-01, 5d
Feature B :a2, 2024-01-03, 4d
Bug Fix :a3, 2024-01-06, 2d
section Integration
Merge to development:b1, after a1, 1d
Integration testing :b2, after b1, 2d
section Release
Promote to staging :c1, after b2, 1d
QA testing :c2, after c1, 3d
Release to main :milestone, after c2, 0d
```
## Examples
### Example 1: Adding a New Feature
**Scenario:** Add user password reset functionality
```bash
# 1. Start from development
git checkout development
git pull origin development
# 2. Create feature branch
git checkout -b feat/password-reset
# 3. Make changes and commit
git add src/auth/password-reset.ts
git commit -m "feat(auth): add password reset request handler"
git add src/email/templates/reset-email.html
git commit -m "feat(email): add password reset email template"
git add tests/auth/password-reset.test.ts
git commit -m "test(auth): add password reset tests"
# 4. Push and create PR
git push -u origin feat/password-reset
# Create PR targeting development
# 5. After merge, cleanup
git checkout development
git pull origin development
git branch -d feat/password-reset
```
### Example 2: Bug Fix
**Scenario:** Fix login timeout issue
```bash
# 1. Create fix branch
git checkout development
git pull origin development
git checkout -b fix/login-timeout
# 2. Fix and commit
git add src/auth/session.ts
git commit -m "fix(auth): increase session timeout to 30 minutes
The default 5-minute timeout was causing frequent re-authentication.
Extended to 30 minutes based on user feedback.
Closes #456"
# 3. Push and create PR
git push -u origin fix/login-timeout
```
### Example 3: Documentation Update
**Scenario:** Update API documentation
```bash
# 1. Create docs branch
git checkout development
git checkout -b docs/api-authentication
# 2. Update docs
git add docs/api/authentication.md
git commit -m "docs(api): document authentication endpoints
Add detailed documentation for:
- POST /auth/login
- POST /auth/logout
- POST /auth/refresh
- GET /auth/me"
# 3. Push and create PR
git push -u origin docs/api-authentication
```
### Example 4: Emergency Hotfix
**Scenario:** Critical security vulnerability in production
```bash
# 1. Create hotfix from main
git checkout main
git pull origin main
git checkout -b hotfix/sql-injection
# 2. Fix the issue
git add src/db/queries.ts
git commit -m "fix(security): sanitize SQL query parameters
CRITICAL: Addresses SQL injection vulnerability in user search.
All user inputs are now properly parameterized.
CVE: CVE-2024-XXXXX"
# 3. Merge to main with tag
git checkout main
git merge hotfix/sql-injection
git tag -a v2.1.1 -m "Hotfix: SQL injection vulnerability"
git push origin main --tags
# 4. Sync to development (IMPORTANT!)
git checkout development
git merge main
git push origin development
# 5. Cleanup
git branch -d hotfix/sql-injection
```
### Example 5: Release Promotion
**Scenario:** Release version 2.2.0
```bash
# 1. Ensure development is ready
git checkout development
git pull origin development
# Run full test suite
npm test
# 2. Update version and changelog
# Edit package.json, CHANGELOG.md
git add package.json CHANGELOG.md
git commit -m "chore(release): prepare v2.2.0"
# 3. Promote to staging
git checkout staging
git merge development
git push origin staging
# 4. After QA approval, promote to main
git checkout main
git merge staging
git tag -a v2.2.0 -m "Release v2.2.0"
git push origin main --tags
# 5. Sync development
git checkout development
git merge main
git push origin development
```
## Configuration
### Environment Variables
Configure the branching strategy via environment variables:
```bash
# Default base branch for new features
GIT_DEFAULT_BASE=development
# Protected branches (comma-separated)
GIT_PROTECTED_BRANCHES=main,master,development,staging,production
# Workflow style
GIT_WORKFLOW_STYLE=feature-branch
# Auto-delete merged branches
GIT_AUTO_DELETE_MERGED=true
```
### Per-Project Configuration
Create `.git-flow.json` in project root:
```json
{
"defaultBase": "development",
"protectedBranches": ["main", "staging", "development"],
"branchPrefixes": ["feat", "fix", "docs", "refactor", "test", "chore"],
"requirePR": {
"main": true,
"staging": true,
"development": false
},
"squashOnMerge": {
"development": true,
"staging": false,
"main": false
}
}
```
## Best Practices
### Do
- Keep feature branches short-lived (< 1 week)
- Rebase feature branches on development regularly
- Write descriptive commit messages
- Delete branches after merging
- Tag all releases on main
- Always sync development after hotfixes
### Avoid
- Long-lived feature branches
- Direct commits to protected branches
- Force pushing to shared branches
- Merging untested code to staging
- Skipping the development sync after hotfixes
## Related Documentation
- [Branching Strategies Skill](/plugins/git-flow/skills/workflow-patterns/branching-strategies.md)
- [git-flow README](/plugins/git-flow/README.md)
- [Conventional Commits](https://www.conventionalcommits.org/)