chore: Add monorepo git workflow and root .gitignore
Added infrastructure for managing BACKEND and FRONTEND as independent components within a single repository: - .gitignore: Root-level exclusions (IDE, OS files, temp files) - GIT-WORKFLOW.md: Comprehensive commit conventions and workflow guide Key conventions: - Use scope prefixes: backend:, frontend:, chore:, docs:, etc. - Commit components independently with clear scopes - Maintain separate history tracking per component - Support coordinated releases when needed This enables: - Independent BACKEND commits (backend: feat/fix/refactor) - Independent FRONTEND commits (frontend: feat/fix/refactor) - Infrastructure commits (chore:, docs:, ci:) - Cross-cutting features when both components change 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
5cd9702a81
commit
c666f6b8d0
38
.gitignore
vendored
Normal file
38
.gitignore
vendored
Normal file
@ -0,0 +1,38 @@
|
||||
# ==============================================================================
|
||||
# CODEX_ADK Root .gitignore
|
||||
# ==============================================================================
|
||||
# This is a monorepo combining BACKEND (ASP.NET Core) and FRONTEND (Flutter)
|
||||
# Each subdirectory has its own .gitignore for component-specific exclusions
|
||||
# ==============================================================================
|
||||
|
||||
# IDE & Editor - Global
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS Files - Global
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
._*
|
||||
|
||||
# Temporary Files
|
||||
*.tmp
|
||||
*.temp
|
||||
*.bak
|
||||
|
||||
# Documentation drafts (keep finalized docs)
|
||||
DRAFT_*.md
|
||||
TODO_*.md
|
||||
NOTES_*.md
|
||||
|
||||
# Local environment overrides
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# Git helper files
|
||||
.git-credentials
|
||||
|
||||
# Project-specific exclusions
|
||||
# (BACKEND and FRONTEND have their own .gitignore files)
|
||||
410
GIT-WORKFLOW.md
Normal file
410
GIT-WORKFLOW.md
Normal file
@ -0,0 +1,410 @@
|
||||
# CODEX_ADK Git Workflow
|
||||
|
||||
## Monorepo Structure
|
||||
|
||||
This is a **monorepo** containing two independent components:
|
||||
|
||||
```
|
||||
CODEX_ADK/ (Root - Combined Project)
|
||||
├── BACKEND/ (ASP.NET Core 8.0 CQRS API)
|
||||
├── FRONTEND/ (Flutter 3.x Console App)
|
||||
├── .gitignore (Root-level exclusions)
|
||||
└── GIT-WORKFLOW.md (This file)
|
||||
```
|
||||
|
||||
## Repository Strategy
|
||||
|
||||
**Single Git Repository** at the root level that:
|
||||
- Tracks both BACKEND and FRONTEND in one repo
|
||||
- Allows independent commits for each component
|
||||
- Maintains clear separation via commit prefixes
|
||||
- Enables coordinated releases when needed
|
||||
|
||||
## Commit Conventions
|
||||
|
||||
### Component-Specific Commits
|
||||
|
||||
Use **scope prefixes** to indicate which component changed:
|
||||
|
||||
```bash
|
||||
# Backend-only changes
|
||||
git commit -m "backend: feat: Add user authentication endpoint"
|
||||
git commit -m "backend: fix: Resolve null reference in AgentService"
|
||||
git commit -m "backend: refactor: Optimize database queries"
|
||||
|
||||
# Frontend-only changes
|
||||
git commit -m "frontend: feat: Add Agents list UI"
|
||||
git commit -m "frontend: fix: API client timeout handling"
|
||||
git commit -m "frontend: style: Update theme colors"
|
||||
|
||||
# Root/Infrastructure changes
|
||||
git commit -m "chore: Update Docker Compose configuration"
|
||||
git commit -m "docs: Add API integration guide"
|
||||
git commit -m "ci: Add GitHub Actions workflow"
|
||||
|
||||
# Changes affecting both (rare)
|
||||
git commit -m "feat: Add conversation feature (backend + frontend)"
|
||||
```
|
||||
|
||||
### Commit Message Format
|
||||
|
||||
```
|
||||
<scope>: <type>: <subject>
|
||||
|
||||
<optional body>
|
||||
|
||||
<optional footer>
|
||||
```
|
||||
|
||||
**Scopes:**
|
||||
- `backend` - ASP.NET Core API changes
|
||||
- `frontend` - Flutter app changes
|
||||
- `chore` - Build, config, dependencies
|
||||
- `docs` - Documentation updates
|
||||
- `ci` - CI/CD pipelines
|
||||
- `test` - Test suite changes
|
||||
|
||||
**Types:**
|
||||
- `feat` - New feature
|
||||
- `fix` - Bug fix
|
||||
- `refactor` - Code restructuring
|
||||
- `perf` - Performance improvement
|
||||
- `style` - Code style/formatting
|
||||
- `test` - Add/update tests
|
||||
- `docs` - Documentation only
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
# Good - Clear component and intent
|
||||
git commit -m "backend: feat: Implement agent execution tracking"
|
||||
git commit -m "frontend: fix: Resolve dialog validation issues"
|
||||
git commit -m "docs: Add OpenAPI integration workflow"
|
||||
|
||||
# Bad - Unclear what changed
|
||||
git commit -m "update code"
|
||||
git commit -m "fixes"
|
||||
git commit -m "WIP"
|
||||
```
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### 1. Backend-Only Changes
|
||||
|
||||
```bash
|
||||
# Make changes to BACKEND files
|
||||
cd BACKEND
|
||||
# ... edit files ...
|
||||
|
||||
# Stage and commit (from root)
|
||||
cd ..
|
||||
git add BACKEND/
|
||||
git commit -m "backend: feat: Add rate limiting middleware"
|
||||
git push
|
||||
```
|
||||
|
||||
### 2. Frontend-Only Changes
|
||||
|
||||
```bash
|
||||
# Make changes to FRONTEND files
|
||||
cd FRONTEND
|
||||
# ... edit files ...
|
||||
|
||||
# Stage and commit (from root)
|
||||
cd ..
|
||||
git add FRONTEND/
|
||||
git commit -m "frontend: feat: Add dark mode toggle"
|
||||
git push
|
||||
```
|
||||
|
||||
### 3. Independent Changes in Same Session
|
||||
|
||||
```bash
|
||||
# Work on both components separately
|
||||
git add BACKEND/Codex.Api/Controllers/AgentsController.cs
|
||||
git commit -m "backend: fix: Validate agent name length"
|
||||
|
||||
git add FRONTEND/lib/screens/agents_screen.dart
|
||||
git commit -m "frontend: feat: Add agent search filter"
|
||||
|
||||
git push
|
||||
```
|
||||
|
||||
### 4. Coordinated Feature (Both Components)
|
||||
|
||||
```bash
|
||||
# When a feature spans both backend and frontend
|
||||
git add BACKEND/ FRONTEND/
|
||||
git commit -m "feat: Add real-time conversation streaming
|
||||
|
||||
BACKEND: Added SignalR hub and streaming endpoints
|
||||
FRONTEND: Added WebSocket client and message UI
|
||||
|
||||
Closes #123"
|
||||
|
||||
git push
|
||||
```
|
||||
|
||||
### 5. Infrastructure Changes
|
||||
|
||||
```bash
|
||||
# Docker, CI/CD, root config
|
||||
git add docker-compose.yml .github/
|
||||
git commit -m "chore: Add PostgreSQL health checks to Docker"
|
||||
git push
|
||||
```
|
||||
|
||||
## Branch Strategy
|
||||
|
||||
### Main Branch
|
||||
- `master` - Production-ready code
|
||||
- Always deployable
|
||||
- Protected (requires PR for merges)
|
||||
|
||||
### Feature Branches
|
||||
|
||||
```bash
|
||||
# Backend feature
|
||||
git checkout -b backend/user-authentication
|
||||
# ... work ...
|
||||
git commit -m "backend: feat: Add JWT authentication"
|
||||
git push origin backend/user-authentication
|
||||
|
||||
# Frontend feature
|
||||
git checkout -b frontend/agents-ui
|
||||
# ... work ...
|
||||
git commit -m "frontend: feat: Add agents management screen"
|
||||
git push origin frontend/agents-ui
|
||||
|
||||
# Cross-cutting feature
|
||||
git checkout -b feature/real-time-chat
|
||||
# ... work on both ...
|
||||
git commit -m "feat: Add real-time chat (backend + frontend)"
|
||||
git push origin feature/real-time-chat
|
||||
```
|
||||
|
||||
### Branch Naming
|
||||
- `backend/*` - Backend features/fixes
|
||||
- `frontend/*` - Frontend features/fixes
|
||||
- `feature/*` - Cross-cutting features
|
||||
- `fix/*` - Bug fixes
|
||||
- `hotfix/*` - Urgent production fixes
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### PR Titles
|
||||
Use same convention as commits:
|
||||
|
||||
```
|
||||
backend: feat: Add user authentication
|
||||
frontend: fix: Resolve dialog validation
|
||||
feat: Add conversation streaming (backend + frontend)
|
||||
```
|
||||
|
||||
### PR Description Template
|
||||
|
||||
```markdown
|
||||
## Component
|
||||
- [ ] Backend
|
||||
- [ ] Frontend
|
||||
- [ ] Both
|
||||
- [ ] Infrastructure
|
||||
|
||||
## Type
|
||||
- [ ] Feature
|
||||
- [ ] Bug Fix
|
||||
- [ ] Refactor
|
||||
- [ ] Documentation
|
||||
|
||||
## Summary
|
||||
Brief description of changes
|
||||
|
||||
## Changes
|
||||
- Change 1
|
||||
- Change 2
|
||||
- Change 3
|
||||
|
||||
## Testing
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Integration tests pass
|
||||
- [ ] Manual testing completed
|
||||
|
||||
## Related Issues
|
||||
Closes #123
|
||||
```
|
||||
|
||||
## Release Strategy
|
||||
|
||||
### Versioning
|
||||
Each component can have independent versions:
|
||||
|
||||
```bash
|
||||
# Tag backend release
|
||||
git tag backend/v1.2.0
|
||||
git push origin backend/v1.2.0
|
||||
|
||||
# Tag frontend release
|
||||
git tag frontend/v1.3.0
|
||||
git push origin frontend/v1.3.0
|
||||
|
||||
# Tag coordinated release
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
```
|
||||
|
||||
### Changelog
|
||||
Maintain separate changelogs:
|
||||
- `BACKEND/CHANGELOG.md` - Backend changes
|
||||
- `FRONTEND/CHANGELOG.md` - Frontend changes
|
||||
- `CHANGELOG.md` - Coordinated releases
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Keep Commits Focused
|
||||
```bash
|
||||
# Good - Single concern
|
||||
git commit -m "backend: fix: Resolve null reference in AgentService"
|
||||
|
||||
# Bad - Multiple concerns
|
||||
git commit -m "backend: fix bugs and add features and update docs"
|
||||
```
|
||||
|
||||
### 2. Commit Frequently
|
||||
```bash
|
||||
# Commit logical units of work
|
||||
git commit -m "backend: feat: Add Agent entity"
|
||||
git commit -m "backend: feat: Add CreateAgentCommand"
|
||||
git commit -m "backend: feat: Add AgentController endpoint"
|
||||
```
|
||||
|
||||
### 3. Write Meaningful Messages
|
||||
```bash
|
||||
# Good
|
||||
git commit -m "frontend: fix: Prevent double-submit on agent creation
|
||||
|
||||
Added disabled state to submit button while request is in flight.
|
||||
This prevents users from accidentally creating duplicate agents.
|
||||
|
||||
Fixes #234"
|
||||
|
||||
# Bad
|
||||
git commit -m "fix stuff"
|
||||
```
|
||||
|
||||
### 4. Review Before Committing
|
||||
```bash
|
||||
# Always review what you're committing
|
||||
git diff
|
||||
git status
|
||||
git add -p # Interactive staging
|
||||
```
|
||||
|
||||
### 5. Keep History Clean
|
||||
```bash
|
||||
# Amend last commit if you forgot something (ONLY if not pushed)
|
||||
git add forgot-this-file.cs
|
||||
git commit --amend --no-edit
|
||||
|
||||
# Squash work-in-progress commits before merging
|
||||
git rebase -i HEAD~3
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Accidentally Committed to Wrong Scope
|
||||
|
||||
```bash
|
||||
# If not pushed yet
|
||||
git reset --soft HEAD~1 # Undo commit, keep changes
|
||||
git add BACKEND/ # Stage correct files
|
||||
git commit -m "backend: fix: Correct scope"
|
||||
|
||||
# If already pushed
|
||||
# Create new commit with correct scope, reference old one in message
|
||||
```
|
||||
|
||||
### Mixed Changes in Working Directory
|
||||
|
||||
```bash
|
||||
# Stage backend changes separately
|
||||
git add BACKEND/
|
||||
git commit -m "backend: feat: Add authentication"
|
||||
|
||||
# Then stage frontend changes
|
||||
git add FRONTEND/
|
||||
git commit -m "frontend: feat: Add login screen"
|
||||
```
|
||||
|
||||
### Checking Component History
|
||||
|
||||
```bash
|
||||
# See all backend commits
|
||||
git log --oneline --grep="^backend:"
|
||||
|
||||
# See all frontend commits
|
||||
git log --oneline --grep="^frontend:"
|
||||
|
||||
# See changes to specific component
|
||||
git log --oneline -- BACKEND/
|
||||
git log --oneline -- FRONTEND/
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
git status
|
||||
|
||||
# Stage component changes
|
||||
git add BACKEND/
|
||||
git add FRONTEND/
|
||||
|
||||
# Commit with scope
|
||||
git commit -m "backend: feat: description"
|
||||
git commit -m "frontend: fix: description"
|
||||
|
||||
# View component history
|
||||
git log --oneline -- BACKEND/
|
||||
git log --oneline -- FRONTEND/
|
||||
|
||||
# Create feature branch
|
||||
git checkout -b backend/feature-name
|
||||
git checkout -b frontend/feature-name
|
||||
|
||||
# Push changes
|
||||
git push origin branch-name
|
||||
|
||||
# Tag release
|
||||
git tag backend/v1.0.0
|
||||
git tag frontend/v1.0.0
|
||||
git push --tags
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
When setting up CI/CD, use path filters:
|
||||
|
||||
```yaml
|
||||
# .github/workflows/backend.yml
|
||||
on:
|
||||
push:
|
||||
paths:
|
||||
- 'BACKEND/**'
|
||||
|
||||
# .github/workflows/frontend.yml
|
||||
on:
|
||||
push:
|
||||
paths:
|
||||
- 'FRONTEND/**'
|
||||
```
|
||||
|
||||
This ensures backend changes only trigger backend builds, and vice versa.
|
||||
|
||||
---
|
||||
|
||||
**Remember:** This monorepo structure allows you to:
|
||||
- Commit backend and frontend changes independently
|
||||
- Maintain clear separation via commit scopes
|
||||
- Track related changes together
|
||||
- Coordinate releases when needed
|
||||
- Keep a unified project history
|
||||
Loading…
Reference in New Issue
Block a user