diff --git a/CloudronPackages/README.md b/CloudronPackages/README.md index c81ebda..0c5cef6 100644 --- a/CloudronPackages/README.md +++ b/CloudronPackages/README.md @@ -67,7 +67,7 @@ docker logs [container-id] 2. **Testing**: Build and validate package functionality 3. **Finalization**: Move completed package to `CloudronPackages/[AppName]/` 4. **Documentation**: Ensure all required files and build notes are complete -5. **Git Workflow**: Commit via feature branch โ†’ integration โ†’ master +5. **Git Workflow**: Commit via feature branch โ†’ integration โ†’ main ### Quality Standards All packages in this directory must meet: diff --git a/GIT_WORKFLOW.md b/GIT_WORKFLOW.md index 74720fe..39e8986 100644 --- a/GIT_WORKFLOW.md +++ b/GIT_WORKFLOW.md @@ -2,40 +2,48 @@ ## ๐ŸŒฟ Branch Strategy -### Branch Hierarchy +### Branch Hierarchy & Workflow Pattern ``` -master (production-ready packages) - โ†‘ merge after validation +main (production-ready packages) + โ†‘ PR (requires YOUR approval) integration (staging for multiple packages) - โ†‘ merge after individual testing + โ†‘ merge feature branch directly (no PR needed) feature/package-[appname] (individual development) - โ†‘ create from master + โ†‘ 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 -#### `master` - Production Branch +#### `main` - Production Branch - **Purpose**: Stable, tested, production-ready packages -- **Protection**: All commits must come via pull request from `integration` -- **Quality Gate**: Packages must be fully tested and validated -- **Release Cadence**: Weekly merges from integration after validation +- **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**: Integration testing of multiple packages together -- **Source**: Merges from individual `feature/package-*` branches -- **Testing**: Cross-package compatibility and integration testing -- **Duration**: Packages stay here for 1-3 days for validation +- **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 `master`, merged to `integration`, then deleted +- **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 `master` -- **Target**: Merge directly to `master` after testing +- **Source**: Created from `main` +- **Target**: Merge directly to `main` after testing - **Examples**: `hotfix/jenkins-security-update` --- @@ -45,9 +53,9 @@ feature/package-[appname] (individual development) ### 1. Starting New Package Development ```bash -# Ensure master is up-to-date -git checkout master -git pull origin master +# Start from integration branch (not main) +git checkout integration +git pull origin integration # Create feature branch git checkout -b feature/package-[appname] @@ -100,19 +108,19 @@ Co-Authored-By: Claude " git push origin feature/package-[appname] ``` -### 4. Integration Process +### 4. Merge to Integration Branch ```bash -# Switch 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 +# Merge feature branch (no PR needed for integration) git merge feature/package-[appname] -# Test integration -# ... run integration tests ... - # Push to integration git push origin integration @@ -121,21 +129,195 @@ git branch -d feature/package-[appname] git push origin --delete feature/package-[appname] ``` -### 5. Production Release +### 5. Production Release via Pull Request ```bash -# After integration validation (1-3 days) -git checkout master -git pull origin master +# When ready for production (multiple packages in integration) +git checkout integration +git pull origin integration -# Merge from integration -git merge 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. -# Tag release +## 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 +``` -# Push with tags -git push origin master --tags +--- + +## ๐Ÿต Gitea & Tea CLI Integration + +### Tea CLI Setup +```bash +# 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 +```bash +# Template for individual package PRs to integration +tea pr create \ + --title "feat(${app_name}): add Cloudron package" \ + --body "$(cat < ### Weekly Release Cycle - **Monday**: Integration branch validation begins - **Wednesday**: Final validation and testing -- **Friday**: Merge to master and tag release +- **Friday**: Merge to main and tag release ### Release Versioning - **Format**: `v2025.01.15` (date-based) @@ -249,7 +431,7 @@ cloudron install --image test/[appname]:feature ### Production Validation ```bash -# Before master merge - production readiness +# Before main merge - production readiness # Full Cloudron deployment testing # Performance and stability validation # Documentation completeness check @@ -267,7 +449,7 @@ cloudron install --image test/[appname]:feature ### Integration Success Rate - **Target**: >95% of packages pass integration testing - **Measurement**: Packages requiring hotfixes after integration -- **Quality Gate**: All tests pass before master merge +- **Quality Gate**: All tests pass before main merge ### Release Stability - **Target**: <5% of releases require hotfixes @@ -279,10 +461,10 @@ cloudron install --image test/[appname]:feature ## ๐Ÿšจ Emergency Procedures ### Critical Package Issue -1. Create `hotfix/[appname]-[issue]` from `master` +1. Create `hotfix/[appname]-[issue]` from `main` 2. Implement minimal fix 3. Test fix thoroughly -4. Merge directly to `master` with approval +4. Merge directly to `main` with approval 5. Cherry-pick to `integration` if needed 6. Update affected downstream deployments diff --git a/PLAN.md b/PLAN.md index ba7813a..1d57d80 100644 --- a/PLAN.md +++ b/PLAN.md @@ -75,7 +75,7 @@ Package ~100 applications for KNEL's Cloudron platform to create a comprehensive ### Git Strategy ``` -master (stable packages) +main (stable packages) โ†‘ integration (testing multiple packages) โ†‘ @@ -91,7 +91,7 @@ feature/package-[appname] (individual development) 6. **Document** โ†’ Create comprehensive build notes 7. **Review** โ†’ Code review and quality assurance 8. **Integrate** โ†’ Merge to integration branch -9. **Release** โ†’ Promote to master after validation +9. **Release** โ†’ Promote to main after validation ### Automation Goals - [ ] Automated testing of package builds diff --git a/README.md b/README.md index a9baac0..5a131b8 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,9 @@ chmod +x CloudronPackagingWorkspace/*.sh ### 2. Create Feature Branch ```bash +# Start from integration branch (not main!) +git checkout integration +git pull origin integration git checkout -b feature/package-[appname] ``` @@ -119,7 +122,7 @@ git push origin feature/package-[appname] ## ๐Ÿท๏ธ Git Workflow ### Branch Strategy -- **`master`**: Stable, production-ready packages +- **`main`**: Stable, production-ready packages - **`integration`**: Integration branch for testing multiple packages - **`feature/package-[appname]`**: Individual application packaging - **`hotfix/[appname]-[issue]`**: Critical fixes