From 57685f333b7796e611efe1278e4fcff45255d58b Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Fri, 5 Sep 2025 07:29:52 -0500 Subject: [PATCH] Add comprehensive git workflow with tagging guidelines and DO/DON'T examples --- AGENT.MD | 28 ++++++++ GIT_WORKFLOW.MD | 174 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 202 insertions(+) create mode 100644 AGENT.MD create mode 100644 GIT_WORKFLOW.MD diff --git a/AGENT.MD b/AGENT.MD new file mode 100644 index 0000000..9cf4fa0 --- /dev/null +++ b/AGENT.MD @@ -0,0 +1,28 @@ +# Agent Guidelines + +This document provides guidelines for AI agents working on this repository. + +## Git Workflow + +All agents must follow the established git workflow documented in [GIT_WORKFLOW.MD](./GIT_WORKFLOW.MD). + +## Key Principles + +1. **Never work on the main branch** - All development must occur on feature branches +2. **Follow the branch structure** as defined in the workflow documentation +3. **Respect the integration and release processes** outlined in the workflow + +## Required Reading + +Before making any commits or branches, agents must review: +- [Git Workflow Documentation](./GIT_WORKFLOW.MD) + +## Branch Usage + +- Use `LLMBOOTSTRAP` for initial setup and bootstrap tasks +- Create new feature branches for specific development tasks +- Ensure all work follows the integration and release pipeline + +## Repository Context + +This repository uses Gitea (not GitHub) for version control and collaboration. \ No newline at end of file diff --git a/GIT_WORKFLOW.MD b/GIT_WORKFLOW.MD new file mode 100644 index 0000000..d8a8512 --- /dev/null +++ b/GIT_WORKFLOW.MD @@ -0,0 +1,174 @@ +# Git Workflow + +This document outlines the git workflow for this repository, designed for use with Gitea. + +## Branch Structure + +### Main Branches + +- **`main`** - The primary stable branch. Direct work should NOT be done on this branch. +- **`RELEASE`** - Production-ready code. Only accepts pull requests that have been manually reviewed and approved. +- **`INTEGRATION-WIP`** - Integration branch where all feature branches are automatically merged for testing and integration. + +### Feature Branches + +- **`LLMBOOTSTRAP`** - Initial bootstrap feature branch for LLM-assisted development setup. +- Additional feature branches should follow naming conventions like `feature/description` or `task/description`. + +## Workflow Rules + +1. **Never work directly on `main`** - All work must be done on feature branches. + +2. **Feature Development Flow:** + - Create feature branches from `main` + - Develop features in isolation on these branches + - Feature branches automatically merge to `INTEGRATION-WIP` for continuous integration testing + +3. **Integration Testing:** + - `INTEGRATION-WIP` branch serves as the integration environment + - All feature branches are automatically merged here + - Used for testing compatibility between different features + +4. **Release Process:** + - Only manually reviewed pull requests are merged to `RELEASE` + - `RELEASE` branch represents production-ready code + - Requires explicit approval before merging + +## Branch Protection + +- `main` - Protected, no direct commits allowed +- `RELEASE` - Protected, only manual PR merges allowed +- `INTEGRATION-WIP` - Accepts automatic merges from feature branches + +## Feature Branch Management + +### **CRITICAL: Branch Preservation** +- **NEVER automatically delete feature branches** under any circumstances +- Feature branches must be preserved for historical reference and potential future work +- Branch deletion should only occur through explicit manual action after careful consideration + +### **Commit and Push Frequency** +- **Commit frequently** - Make small, logical commits as you work +- **Push every 10 commits maximum** - Don't let local commits accumulate +- **ALWAYS push before switching branches** - Ensure work is backed up remotely +- **Push immediately before any branch operations** (merge, rebase, etc.) + +### **Tagging for Milestones** +- **Create tags when interim stages or milestones are completed** +- **Push tags immediately after creation** to preserve milestone markers +- **Tag naming conventions:** + - Date-based: `milestone-YYYY-MM-DD` or `stage-YYYY-MM-DD-HHMM` + - Stage-based: `bootstrap-complete`, `auth-module-done`, `integration-ready` + - Plan-based: Use milestone names from planning documents +- **Always annotate tags** with meaningful descriptions of what was accomplished + +## Best Practices + +- Keep feature branches focused and small +- Use descriptive branch names +- Regularly sync feature branches with `main` +- Test thoroughly in `INTEGRATION-WIP` before requesting merge to `RELEASE` +- Write clear commit messages and PR descriptions +- Follow the commit/push frequency rules above + +## Examples: DO and DON'T + +### ✅ **DO Examples** + +```bash +# DO: Create feature branch from main +git checkout main +git pull origin main +git checkout -b feature/user-authentication + +# DO: Commit frequently with descriptive messages +git add . +git commit -m "Add user login form validation" +git commit -m "Implement password hashing utility" +git commit -m "Add user session management" + +# DO: Push after every 10 commits or before switching branches +git push origin feature/user-authentication + +# DO: Push before switching to another branch +git push origin feature/user-authentication +git checkout feature/payment-system + +# DO: Sync feature branch with main regularly +git checkout main +git pull origin main +git checkout feature/user-authentication +git merge main + +# DO: Tag milestones with descriptive annotations +git tag -a bootstrap-complete -m "Initial project structure and workflow setup completed" +git push origin bootstrap-complete + +# DO: Use date-based tags for interim stages +git tag -a stage-2025-09-05-1430 -m "Authentication module implementation complete" +git push origin stage-2025-09-05-1430 +``` + +### ❌ **DON'T Examples** + +```bash +# DON'T: Work directly on main +git checkout main +git add . +git commit -m "Fix user auth bug" # ❌ NEVER DO THIS + +# DON'T: Delete feature branches automatically +git branch -d feature/user-authentication # ❌ NEVER DO THIS +git push origin --delete feature/user-authentication # ❌ NEVER DO THIS + +# DON'T: Let commits accumulate without pushing +git log --oneline # Shows 15+ unpushed commits # ❌ Should have pushed earlier + +# DON'T: Switch branches without pushing current work +git checkout feature/payment-system # ❌ Without pushing current branch first + +# DON'T: Make massive commits +git add . +git commit -m "Complete entire user system" # ❌ Too broad, break it down + +# DON'T: Create tags without annotations +git tag milestone-1 # ❌ No description of what was accomplished +git push origin milestone-1 + +# DON'T: Forget to push tags +git tag -a bootstrap-complete -m "Setup complete" +# ❌ Missing: git push origin bootstrap-complete +``` + +### 🔧 **Workflow Examples** + +**Starting new feature:** +```bash +git checkout main +git pull origin main +git checkout -b feature/shopping-cart +# Work, commit frequently, push every ~10 commits +``` + +**Switching between features:** +```bash +# Currently on feature/shopping-cart +git add . +git commit -m "Add item quantity validation" +git push origin feature/shopping-cart # ✅ Push before switching +git checkout feature/user-profile +``` + +**Preparing for integration:** +```bash +git checkout feature/shopping-cart +git push origin feature/shopping-cart +# Feature automatically merges to INTEGRATION-WIP +``` + +## Gitea Integration + +This workflow is optimized for Gitea and utilizes: +- Branch protection rules +- Automatic merge capabilities for integration testing +- Manual review processes for production releases \ No newline at end of file