🌿Branch Management

Comprehensive branch management documentation including implementation details, strategy, and workflow guidelines.

Table of Contents

Overview

This document provides complete guidance on branch management for the ProxmoxMCP project, covering both the implemented tools and strategic workflow processes. The branch management system ensures consistent naming conventions, quality gates, and efficient development workflows.

Implementation Summary (PR #67)

Comprehensive Branch Management System Implementation

Successfully implemented a comprehensive branch management system for the ProxmoxMCP project that addresses all shell script issues and provides robust branch naming validation and management tools.

✅ Issues Resolved

Shell Script Issues (~30 issues)

File: scripts/branch-templates/config.sh

  • ✅ Missing shebang (SC2148): Added proper #!/usr/bin/env bash shebang

  • ✅ Multiple unused variables (SC2034): All variables are now properly exported for external use

  • ✅ Error handling: Added set -euo pipefail for robust error handling

File: scripts/branch-templates/validate.sh

  • ✅ Use ${variable//search/replace} instead of sed (SC2001): Replaced all sed usage with bash parameter expansion

  • ✅ Unused variable suggestions: All variables are properly used throughout the script

  • ✅ Proper shebang and error handling: Consistent with best practices

Additional Improvements

  • ✅ Shellcheck compliance: All scripts pass shellcheck validation

  • ✅ Consistent coding standards: Follow existing project patterns

  • ✅ Proper documentation: Comprehensive inline comments and help text

📁 Files Created

Core Scripts

  1. scripts/branch-templates/config.sh (108 lines)

    • Central configuration for branch management system

    • Exported variables for external script usage

    • Shared functions for validation logic

    • User-configurable settings support

  2. scripts/branch-templates/validate.sh (386 lines)

    • Comprehensive branch name validation

    • Multiple validation layers (length, prefix, component, description, characters)

    • Helpful error messages and suggestions

    • Support for current branch and specific name validation

  3. scripts/branch-templates/branch-manager.sh (330 lines)

    • Main interface for branch management operations

    • Interactive branch creation with guided prompts

    • Branch listing with validation status indicators

    • Merged branch cleanup functionality

    • Comprehensive help system

  4. scripts/branch-templates/README.md (165 lines)

    • Complete documentation and usage guide

    • Quick start examples

    • Configuration options

    • Git hooks integration examples

    • Troubleshooting guide

Supporting Files

  1. BRANCH_MANAGEMENT_SUMMARY.md (This file's source)

    • Implementation summary and testing results

🎯 Features Implemented

Branch Naming Convention Enforcement

  • Format: <type>/<component>-<description>

  • Valid Types: feature, fix, security, docker, config, docs, ci, perf

  • Valid Components: vm, container, storage, network, backup, auth, encryption, config, api, mcp, core, tools, formatting, docker, proxmox, console, management

  • Length Validation: 10-80 characters (configurable)

  • Character Validation: Only alphanumeric, hyphens, and forward slashes

  • Description Requirements: Meaningful descriptive suffix after component

Interactive Tools

  • Branch Creation: Guided prompts for type, component, and description selection

  • Validation: Current branch or specific name validation with detailed feedback

  • Branch Listing: Visual status indicators (✅ valid, ❌ invalid, 🛡️ protected)

  • Cleanup: Safe removal of merged branches with dry-run option

Configuration System

  • Default Settings: Sensible defaults for immediate use

  • User Customization: Optional .branch-config file for overrides

  • Protected Branches: Automatic recognition of main, develop, staging

  • Component Extensibility: Easy addition of new valid components

🧪 Testing Results

Validation Testing

Help System Testing

Script Quality Verification

  • ✅ All scripts are executable (chmod +x applied)

  • ✅ Proper error handling with set -euo pipefail

  • ✅ No shellcheck warnings or errors

  • ✅ Consistent with existing project shell script patterns

  • ✅ No unused variables (all exported for external use)

  • ✅ Parameter expansion used instead of sed (addresses SC2001)

🚀 Usage Examples

Quick Start

Advanced Usage

🔧 Integration Options

Git Hooks Integration

The system can be integrated with Git hooks for automatic enforcement:

  • Pre-push validation to prevent invalid branch names

  • Pre-commit validation for branch name compliance

  • Examples provided in documentation

CI/CD Integration

Scripts can be incorporated into CI/CD pipelines for branch name validation during pull request creation.

📊 Impact Assessment

Code Quality Improvements

  • Shell Script Standards: All scripts follow best practices and are shellcheck compliant

  • Error Handling: Robust error handling with proper exit codes

  • Documentation: Comprehensive documentation for maintainability

  • User Experience: Intuitive interface with helpful error messages and suggestions

Development Workflow Enhancement

  • Consistency: Enforces consistent branch naming across the project

  • Guidance: Interactive tools help developers create properly named branches

  • Maintenance: Automated cleanup of merged branches

  • Validation: Early detection of naming convention violations

Maintainability

  • Modular Design: Separate configuration, validation, and management components

  • Extensibility: Easy to add new branch types and components

  • Configuration: User-customizable settings without code changes

  • Testing: All functionality tested and verified

✅ Completion Status

Status: COMPLETE ✨

All shell script issues have been resolved and the comprehensive branch management system has been successfully implemented with:

  • ✅ 30+ shell script issues addressed

  • ✅ 4 new files created with 989 total lines of code

  • ✅ Complete documentation and usage examples

  • ✅ Full testing and validation

  • ✅ Integration-ready with Git hooks and CI/CD systems

The branch management system is ready for immediate use and provides a solid foundation for maintaining consistent branch naming conventions across the ProxmoxMCP project.

Branching Strategy

Enhanced GitHub Flow

This section outlines the branching strategy and workflow for the ProxmoxMCP repository to ensure consistent, high-quality development practices.

Branch Types

1. main Branch

  • Purpose: Production-ready code, always deployable

  • Protection: Fully protected, no direct pushes

  • Merge Requirements: PR review + CI checks passing

2. Feature Branches

3. Fix Branches

4. Security Branches

5. Maintenance Branches

6. Release Branches (Optional)

7. Hotfix Branches

Workflow Processes

Standard Development Workflow

1. Start New Work

2. Create Pull Request

  • Use PR template checklist

  • Link related issues

  • Add appropriate labels

  • Request relevant reviewers

  • Ensure all CI checks pass

3. Review Process

  • Address review feedback

  • Keep commits clean and logical

  • Squash commits if necessary before merge

4. Merge and Cleanup

Emergency Hotfix Workflow

Release Workflow

Branch Protection Rules

Main Branch Protection

  • ✅ Require pull request reviews before merging (minimum: 1)

  • ✅ Require status checks to pass before merging

    • Codacy quality checks

    • CI/CD workflows (autofix, yaml-lint)

    • Security scans

  • ✅ Require branches to be up to date before merging

  • ✅ Restrict pushes to matching branches

  • ✅ Do not allow bypassing the above settings

  • ✅ Allow force pushes: disabled

  • ✅ Allow deletions: disabled

Quality Gates

All PRs must pass:

  1. Automated Checks

    • Codacy quality assessment

    • Security vulnerability scans

    • Linting (ruff, black, mypy)

    • Test suite (pytest)

  2. Manual Review

    • Code quality review

    • Security review (for security changes)

    • Documentation review (for docs changes)

Best Practices

PR Review Guidelines

For Reviewers

Security Changes

Code Changes

Documentation Changes

For Contributors

Before Creating PR

PR Description Template

Integration with Existing Tools

Codacy Integration

  • All PRs must pass Codacy quality gates

  • Security issues must be addressed before merge

  • Code complexity limits enforced

Dependabot Integration

  • Automated dependency PRs get dependencies label

  • Security updates get expedited review

  • Breaking changes require manual testing

CI/CD Workflows

  • autofix.yml: Automated formatting fixes

  • claude-auto-review.yml: AI-assisted code review

  • yaml-lint.yml: YAML file validation

  • All workflows must pass for PR merge

Migration Plan

Phase 1: Foundation (Week 1)

  1. Update branch protection rules

  2. Create PR and issue templates

  3. Document new workflow (this guide)

  4. Train team on new process

Phase 2: Process Rollout (Week 2)

  1. Apply new workflow to all new PRs

  2. Migrate any existing feature work to proper branches

  3. Update CI/CD to enforce new rules

Phase 3: Optimization (Week 3-4)

  1. Monitor adoption and address issues

  2. Refine review process based on experience

  3. Add additional automation as needed

  4. Create release process documentation

Troubleshooting

Common Issues

Q: What if I accidentally committed to main? A: Create a revert commit, then properly implement the change in a feature branch.

Q: How do I handle conflicts during rebase? A:

Q: What if CI checks fail? A: Fix the issues locally, commit the fixes, and push to update the PR.

Q: Emergency fix needed in production? A: Use hotfix workflow with fast-track review process.

Benefits of This Strategy

  1. Quality Assurance: All changes reviewed and tested

  2. Security Focus: Mandatory security reviews for sensitive changes

  3. Automation Integration: Leverages existing Codacy/CI infrastructure

  4. Flexibility: Supports different types of changes appropriately

  5. Traceability: Clear history and relationship to issues

  6. Collaboration: Encourages code review and knowledge sharing

Next Steps

  1. Implement branch protection rules

  2. Create PR/issue templates

  3. Update CI/CD workflows if needed

  4. Begin using new workflow for all changes

  5. Monitor and refine process based on team feedback

This document provides comprehensive branch management guidance for ProxmoxMCP, combining implementation details with strategic workflow processes.

PreviousMilestone PlanningNextClaude Code Automation

Last updated

Was this helpful?