KNEL/KNELProductionContainers
2
0
Fork 0
Code Pull Requests Actions Packages Releases Activity
Files
integration
KNELProductionContainers/docs/GIT_WORKFLOW.md

14 KiB
Raw Permalink Blame History

Git Workflow for Cloudron Packaging

🌿 Branch Strategy

Branch Hierarchy & Workflow Pattern

main (production-ready packages)
  ↑ PR (requires YOUR approval)
integration (staging for multiple packages)  
  ↑ merge feature branch directly (no PR needed)
feature/package-[appname] (individual development)
  ↑ create from integration

One Package = One Branch Pattern:

  1. Create feature/package-[appname] from integration
  2. Develop complete package in feature branch
  3. Merge feature branch to integration (direct merge)
  4. When multiple packages ready, create PR integration → main (requires your approval)

Branch Purposes

main - Production Branch

  • Purpose: Stable, tested, production-ready packages
  • Protection: ALL commits must come via Pull Request from integration
  • Approval Required: Project maintainer approval mandatory
  • Quality Gate: Full validation and approval before merge
  • Branch Protection: Direct pushes blocked, PR reviews required

integration - Staging Branch

  • Purpose: Collection point for completed packages before production
  • Source: Direct merges from individual feature/package-* branches (no PR needed)
  • Protection: Open for direct pushes from feature branches
  • Testing: Integration testing and cross-package validation
  • Duration: Accumulates packages until batch ready for production release

feature/package-[appname] - Development Branches

  • Purpose: Individual application packaging development
  • Naming: feature/package-jenkins, feature/package-apisix, etc.
  • Lifespan: Created from main, merged to integration, then deleted
  • Scope: Single application focus, complete package development

hotfix/[appname]-[issue] - Emergency Fixes

  • Purpose: Critical fixes to existing packages
  • Source: Created from main
  • Target: Merge directly to main after testing
  • Examples: hotfix/jenkins-security-update

🔄 Development Workflow

1. Starting New Package Development

# Start from integration branch (not main)
git checkout integration
git pull origin integration

# Create feature branch
git checkout -b feature/package-[appname]

# Push branch to remote
git push -u origin feature/package-[appname]

2. Development Process

# Work in containerized environment
docker exec -it tsys-cloudron-packaging bash
cd /workspace

# Create package
mkdir -p [appname]_package_new
cd [appname]_package_new
# ... develop package files ...

# Test package
docker build -t test/[appname]:dev .
docker run --rm test/[appname]:dev

# Move to final location when ready
mv /workspace/[appname]_package_new ./CloudronPackages/[AppName]/

3. Committing Changes

# Add package files
git add CloudronPackages/[AppName]/

# Update task tracking
git add TASKS.md WORKLOG.md

# Commit with proper message
git commit -m "feat([appname]): add Cloudron package

- Implements [AppName] packaging for Cloudron platform
- Includes proper addon integration and health checks
- Tested with build and basic functionality
- Estimated complexity: [Low/Medium/High]

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>"

# Push to remote
git push origin feature/package-[appname]

4. Merge to Integration Branch

# Push final changes to feature branch
git push origin feature/package-[appname]

# Switch to integration and merge feature branch directly
git checkout integration
git pull origin integration

# Merge feature branch (no PR needed for integration)
git merge feature/package-[appname]

# Push to integration
git push origin integration

# Clean up feature branch
git branch -d feature/package-[appname]
git push origin --delete feature/package-[appname]

5. Production Release via Pull Request

# When ready for production (multiple packages in integration)
git checkout integration
git pull origin integration

# Create PR from integration to main using tea CLI
tea pr create \
  --title "release: $(date +%Y-%m-%d) package release" \
  --body "$(cat <<'EOF'
## Release Summary
Production release containing validated packages ready for deployment.

## Packages Included
- [AppName1]: [brief description]
- [AppName2]: [brief description]
- [AppName3]: [brief description]

## Validation Completed
- [x] All packages build successfully
- [x] Integration testing completed
- [x] No conflicts between packages
- [x] Documentation updated
- [x] Quality standards met

## Impact
- Ready for production deployment
- No breaking changes
- All packages follow established patterns

**Requires maintainer approval before merge**
EOF
)" \
  --base main \
  --head integration

# Wait for maintainer approval and merge
# After merge, tag the release
git checkout main
git pull origin main
git tag -a v$(date +%Y.%m.%d) -m "Release $(date +%Y-%m-%d): [package list]"
git push origin main --tags

🍵 Gitea & Tea CLI Integration

Tea CLI Setup

# Install tea CLI (if not already installed)
# Visit: https://gitea.com/gitea/tea#installation

# Configure tea for your Gitea instance
tea login add --name knel --url https://git.knownelement.com --token [your-token]

# Verify configuration
tea whoami

PR Templates with Tea

Feature Package PR Template

# Template for individual package PRs to integration
tea pr create \
  --title "feat(${app_name}): add Cloudron package" \
  --body "$(cat <<EOF
## 📦 Package: ${app_name}

### Summary
Implements ${app_name} Cloudron package with proper addon integration and follows established patterns.

### 🔧 Technical Details
- **Base Image**: cloudron/base:4.2.0
- **Addons Required**: ${addons_list}
- **Memory Limit**: ${memory_limit}MB
- **Health Check**: ${health_check_path}
- **Complexity**: ${complexity}

### 📋 Changes
- ✅ CloudronManifest.json with proper addon configuration
- ✅ Dockerfile following Cloudron conventions  
- ✅ start.sh with initialization and error handling
- ✅ Configuration files and templates
- ✅ Build notes documentation

### 🧪 Testing Checklist
- [x] Docker build successful
- [x] Basic functionality verified
- [x] Health check endpoint working
- [x] Addon integration tested
- [ ] Full Cloudron deployment test (if available)

### 📚 Documentation
- [x] Build notes complete
- [x] Configuration documented
- [x] Known limitations noted
- [x] TASKS.md updated

**Auto-merge after CI passes ✅**
EOF
)" \
  --base integration \
  --head feature/package-${app_name}

Production Release PR Template

# Template for integration → main PRs (requires approval)
tea pr create \
  --title "release: $(date +%Y-%m-%d) production package release" \
  --body "$(cat <<EOF
## 🚀 Production Release: $(date +%B %d, %Y)

### 📦 Packages Ready for Production
$(git log --oneline integration ^main --grep="feat(" | sed 's/.*feat(\([^)]*\)).*/- **\1**: Ready for deployment/')

### ✅ Validation Summary
- [x] All packages build successfully without errors
- [x] Integration testing completed across packages  
- [x] No resource conflicts or port collisions
- [x] Documentation complete and up-to-date
- [x] Quality standards met for all packages
- [x] Security review completed

### 🔍 Quality Gates Passed
- **Build Success Rate**: 100%
- **Test Coverage**: All packages validated
- **Documentation**: Complete
- **Standards Compliance**: ✅

### 📊 Impact Assessment  
- **New Packages**: $(git log --oneline integration ^main --grep="feat(" | wc -l)
- **Breaking Changes**: None
- **Deployment Risk**: Low
- **Rollback Plan**: Available

### 🎯 Post-Merge Actions
- [ ] Tag release: v$(date +%Y.%m.%d)
- [ ] Update deployment documentation
- [ ] Notify deployment team
- [ ] Monitor initial deployments

**⚠️ REQUIRES MAINTAINER APPROVAL ⚠️**
EOF
)" \
  --base main \
  --head integration

Tea CLI Common Commands

# List open PRs
tea pr list

# Check PR status
tea pr view [pr-number]

# Close/merge PR (for maintainers)
tea pr merge [pr-number]

# Create draft PR
tea pr create --draft

# Add reviewers to PR
tea pr create --reviewer @maintainer

# Link PR to issue
tea pr create --body "Closes #123"

Automated Workflow Helpers

# Quick PR creation function (add to ~/.bashrc)
create_package_pr() {
  local app_name=$1
  local complexity=${2:-"Medium"}
  local addons=${3:-"localstorage, postgresql"}
  
  tea pr create \
    --title "feat(${app_name}): add Cloudron package" \
    --body "Implements ${app_name} package. Complexity: ${complexity}. Addons: ${addons}" \
    --base integration \
    --head feature/package-${app_name}
}

# Usage: create_package_pr "jenkins" "High" "localstorage, postgresql, redis"

📋 Commit Message Standards

Commit Types

  • feat(app): New package implementation
  • fix(app): Bug fix in existing package
  • docs: Documentation updates
  • chore: Maintenance tasks
  • test: Testing improvements
  • refactor(app): Package improvements without functional changes

Message Format

type(scope): brief description

Detailed description of changes:
- Key changes made
- Testing performed  
- Any breaking changes or considerations

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>

Examples

feat(jenkins): add Jenkins CI/CD Cloudron package

- Implements complete Jenkins packaging with persistent storage
- Includes supervisor configuration for multi-process management
- Integrates with PostgreSQL addon for build history
- Tested with basic job creation and execution

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>

fix(apisix): resolve etcd connection timeout issue

- Increases etcd connection timeout from 5s to 30s
- Adds proper wait-for-etcd startup logic
- Improves error logging for debugging
- Tested with cold start scenarios

🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <noreply@anthropic.com>

🛡️ Branch Protection Rules

Master Branch Protection

  • Require pull request reviews: 1 approver minimum
  • Dismiss stale reviews: When new commits pushed
  • Require status checks: All CI/CD passes
  • Require branches up to date: Before merging
  • Include administrators: Apply rules to admins

Integration Branch Protection

  • Require pull request reviews: 1 approver (can be self-approved)
  • Allow force pushes: For integration management
  • Delete head branches: Automatic cleanup

🔄 Release Management

Weekly Release Cycle

  • Monday: Integration branch validation begins
  • Wednesday: Final validation and testing
  • Friday: Merge to main and tag release

Release Versioning

  • Format: v2025.01.15 (date-based)
  • Tags: Annotated tags with package list
  • Notes: Generated from commit messages

Release Content

Each release includes:

  • List of new packages added
  • List of packages updated
  • Known issues or limitations
  • Upgrade instructions if needed

🧪 Testing Strategy

Individual Package Testing

# In feature branch - basic functionality
docker build -t test/[appname]:feature .
docker run --rm -p 8080:8080 test/[appname]:feature

# Local Cloudron testing (if available)
cloudron install --image test/[appname]:feature

Integration Testing

# In integration branch - cross-package testing
# Test multiple packages don't conflict
# Verify resource usage within limits
# Check for port conflicts or naming issues

Production Validation

# Before main merge - production readiness
# Full Cloudron deployment testing
# Performance and stability validation
# Documentation completeness check

📊 Workflow Metrics

Development Velocity

  • Target: 2-3 packages per week
  • Measurement: Feature branch creation to integration merge
  • Quality Gate: Zero critical issues in integration

Integration Success Rate

  • Target: >95% of packages pass integration testing
  • Measurement: Packages requiring hotfixes after integration
  • Quality Gate: All tests pass before main merge

Release Stability

  • Target: <5% of releases require hotfixes
  • Measurement: Hotfix commits per release
  • Quality Gate: Production stability maintained

🚨 Emergency Procedures

Critical Package Issue

  1. Create hotfix/[appname]-[issue] from main
  2. Implement minimal fix
  3. Test fix thoroughly
  4. Merge directly to main with approval
  5. Cherry-pick to integration if needed
  6. Update affected downstream deployments

Integration Branch Issues

  1. Identify problematic package
  2. Revert specific merge if possible
  3. Return package to feature branch for fixes
  4. Re-test integration after fix

Repository Corruption

  1. Backup current state
  2. Identify last known good state
  3. Reset affected branches
  4. Reapply recent changes manually if needed
  5. Communicate impact to team

🔧 Git Configuration

Recommended Git Config

# Helpful aliases
git config --global alias.co checkout
git config --global alias.br branch  
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'
git config --global alias.visual '!gitk'

# Better logging
git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

# Push settings
git config --global push.default simple
git config --global pull.rebase true

Team Settings

# Consistent line endings
git config --global core.autocrlf input

# Editor setup
git config --global core.editor "code --wait"

# Name and email (team members)
git config --global user.name "Your Name"
git config --global user.email "your.email@knel.com"

Last Updated: 2025-01-04
Next Review: 2025-02-01
Maintained By: KNEL/TSYS Development Team