docs: restructure documentation into organized folders
Some checks failed
Deploy to Coolify / Code Quality (pull_request) Has been cancelled
Deploy to Coolify / Run Tests (pull_request) Has been cancelled
Deploy to Coolify / Deploy to Development (pull_request) Has been cancelled
Deploy to Coolify / Deploy to Production (pull_request) Has been cancelled
Deploy to Coolify / Deploy to Test (pull_request) Has been cancelled
Pull Request Checks / Validate PR (pull_request) Has been cancelled
Some checks failed
Deploy to Coolify / Code Quality (pull_request) Has been cancelled
Deploy to Coolify / Run Tests (pull_request) Has been cancelled
Deploy to Coolify / Deploy to Development (pull_request) Has been cancelled
Deploy to Coolify / Deploy to Production (pull_request) Has been cancelled
Deploy to Coolify / Deploy to Test (pull_request) Has been cancelled
Pull Request Checks / Validate PR (pull_request) Has been cancelled
Organized docs into logical subdirectories:
**New Structure:**
- docs/
- README.md (index with quick links)
- PROJECT_PLAN.md (root level - main roadmap)
- development/
- getting-started.md (5-min quickstart)
- local-setup.md (detailed Docker Compose guide)
- workflow.md (daily development)
- git-workflow.md (branching strategy)
- architecture/
- overview.md (tech stack, design)
- database.md (schema, RLS, migrations)
- api.md (endpoints, functions)
- deployment/
- production.md (Docker, Coolify)
- ci-cd.md (automated pipelines)
**Cleaned Up:**
- Moved DEV_SETUP.md → docs/development/local-setup.md
- Removed outdated SETUP.md (referenced old Coolify setup)
- Replaced with getting-started.md (current Docker Compose flow)
- Updated README.md links to new structure
All paths tested, no broken links.
This commit is contained in:
Pantry Lead Agent
358
docs/development/git-workflow.md
Normal file
358
docs/development/git-workflow.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# Pantry - Branching Strategy
|
||||
|
||||
## 🌿 Branch Structure
|
||||
|
||||
```
|
||||
main (production)
|
||||
↑
|
||||
└── develop (development)
|
||||
↑
|
||||
├── feature/barcode-scanner
|
||||
├── feature/tag-system
|
||||
├── fix/quantity-bug
|
||||
└── chore/update-deps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Branch Types
|
||||
|
||||
### `main` - Production
|
||||
|
||||
- **Purpose:** Production-ready code
|
||||
- **Protection:** Require PR approval
|
||||
- **Deploy:** Auto-deploy to production on push
|
||||
- **Stability:** Must always be stable
|
||||
|
||||
**Rules:**
|
||||
- Never commit directly
|
||||
- Only merge from `develop` via release PR
|
||||
- All merges must pass CI/CD checks
|
||||
|
||||
### `develop` - Development
|
||||
|
||||
- **Purpose:** Integration branch for features
|
||||
- **Protection:** Require PR approval (optional)
|
||||
- **Deploy:** Auto-deploy to dev environment on push
|
||||
- **Stability:** Should be stable, but can have minor issues
|
||||
|
||||
**Rules:**
|
||||
- Never commit directly (except hotfixes)
|
||||
- Merge features via PR
|
||||
- Keep in sync with `main` regularly
|
||||
|
||||
### `feature/*` - Features
|
||||
|
||||
- **Purpose:** New features or enhancements
|
||||
- **Naming:** `feature/short-description`
|
||||
- **Base:** Branch from `develop`
|
||||
- **Merge:** PR to `develop`
|
||||
|
||||
**Examples:**
|
||||
- `feature/barcode-scanner`
|
||||
- `feature/tag-management`
|
||||
- `feature/unit-conversions`
|
||||
|
||||
### `fix/*` - Bug Fixes
|
||||
|
||||
- **Purpose:** Fix bugs in `develop`
|
||||
- **Naming:** `fix/short-description`
|
||||
- **Base:** Branch from `develop`
|
||||
- **Merge:** PR to `develop`
|
||||
|
||||
**Examples:**
|
||||
- `fix/quantity-validation`
|
||||
- `fix/tag-duplication`
|
||||
|
||||
### `hotfix/*` - Production Hotfixes
|
||||
|
||||
- **Purpose:** Critical fixes for production
|
||||
- **Naming:** `hotfix/short-description`
|
||||
- **Base:** Branch from `main`
|
||||
- **Merge:** PR to both `main` AND `develop`
|
||||
|
||||
**Examples:**
|
||||
- `hotfix/auth-bypass`
|
||||
- `hotfix/data-corruption`
|
||||
|
||||
**Process:**
|
||||
```bash
|
||||
git checkout main
|
||||
git pull
|
||||
git checkout -b hotfix/critical-bug
|
||||
# Fix bug
|
||||
git push origin hotfix/critical-bug
|
||||
# Create PR to main (deploy immediately)
|
||||
# Create second PR to develop (keep in sync)
|
||||
```
|
||||
|
||||
### `release/*` - Releases
|
||||
|
||||
- **Purpose:** Prepare for production release
|
||||
- **Naming:** `release/v0.1.0`
|
||||
- **Base:** Branch from `develop`
|
||||
- **Merge:** PR to `main` (then tag)
|
||||
|
||||
**Process:**
|
||||
```bash
|
||||
git checkout develop
|
||||
git pull
|
||||
git checkout -b release/v0.1.0
|
||||
# Update version, changelog, docs
|
||||
git push origin release/v0.1.0
|
||||
# Create PR to main
|
||||
# After merge, tag main with v0.1.0
|
||||
```
|
||||
|
||||
### `chore/*` - Maintenance
|
||||
|
||||
- **Purpose:** Dependencies, configs, tooling
|
||||
- **Naming:** `chore/short-description`
|
||||
- **Base:** Branch from `develop`
|
||||
- **Merge:** PR to `develop`
|
||||
|
||||
**Examples:**
|
||||
- `chore/update-nuxt`
|
||||
- `chore/eslint-config`
|
||||
- `chore/ci-improvements`
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Workflow Examples
|
||||
|
||||
### Adding a Feature
|
||||
|
||||
```bash
|
||||
# 1. Start from develop
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
|
||||
# 2. Create feature branch
|
||||
git checkout -b feature/barcode-scanner
|
||||
|
||||
# 3. Work on feature
|
||||
# ... make changes ...
|
||||
|
||||
# 4. Commit regularly
|
||||
git add .
|
||||
git commit -m "feat: Add barcode detection logic"
|
||||
|
||||
# 5. Push to remote
|
||||
git push origin feature/barcode-scanner
|
||||
|
||||
# 6. Create PR to develop on Gitea
|
||||
# Review → Merge → Auto-deploys to dev
|
||||
```
|
||||
|
||||
### Releasing to Production
|
||||
|
||||
```bash
|
||||
# 1. Ensure develop is stable
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
|
||||
# 2. Create release branch
|
||||
git checkout -b release/v0.1.0
|
||||
|
||||
# 3. Update version and changelog
|
||||
# Edit package.json, CHANGELOG.md
|
||||
|
||||
# 4. Commit and push
|
||||
git commit -am "chore: Prepare v0.1.0 release"
|
||||
git push origin release/v0.1.0
|
||||
|
||||
# 5. Create PR to main
|
||||
# Review → Merge → Auto-deploys to production
|
||||
|
||||
# 6. Tag the release
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git tag -a v0.1.0 -m "Release v0.1.0"
|
||||
git push origin v0.1.0
|
||||
|
||||
# 7. Merge back to develop (keep in sync)
|
||||
git checkout develop
|
||||
git merge main
|
||||
git push origin develop
|
||||
```
|
||||
|
||||
### Hotfix Production Issue
|
||||
|
||||
```bash
|
||||
# 1. Branch from main
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b hotfix/auth-bypass
|
||||
|
||||
# 2. Fix the issue
|
||||
# ... fix ...
|
||||
|
||||
# 3. Commit and push
|
||||
git commit -am "fix: Patch authentication bypass"
|
||||
git push origin hotfix/auth-bypass
|
||||
|
||||
# 4. Create PR to main
|
||||
# Urgent review → Merge → Immediate deploy
|
||||
|
||||
# 5. Also PR to develop (keep in sync)
|
||||
git checkout develop
|
||||
git pull origin develop
|
||||
git checkout -b hotfix/auth-bypass-to-develop
|
||||
git merge hotfix/auth-bypass
|
||||
git push origin hotfix/auth-bypass-to-develop
|
||||
# Create second PR to develop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Commit Message Convention
|
||||
|
||||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
- `feat`: New feature
|
||||
- `fix`: Bug fix
|
||||
- `docs`: Documentation only
|
||||
- `style`: Code style (formatting, no logic change)
|
||||
- `refactor`: Code refactoring
|
||||
- `test`: Adding/updating tests
|
||||
- `chore`: Maintenance (deps, configs)
|
||||
- `perf`: Performance improvement
|
||||
|
||||
### Examples
|
||||
|
||||
```bash
|
||||
feat(scan): Add barcode scanner component
|
||||
fix(inventory): Prevent negative quantities
|
||||
docs(api): Update product lookup examples
|
||||
chore(deps): Upgrade Nuxt to 4.1.2
|
||||
refactor(tags): Simplify tag picker logic
|
||||
test(units): Add conversion edge cases
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Branch Protection Rules
|
||||
|
||||
### `main` (Production)
|
||||
|
||||
- ✅ Require pull request before merging
|
||||
- ✅ Require status checks to pass
|
||||
- ✅ Require review from code owner (1+)
|
||||
- ✅ Dismiss stale approvals
|
||||
- ❌ Allow force push
|
||||
- ❌ Allow deletions
|
||||
|
||||
### `develop` (Development)
|
||||
|
||||
- ✅ Require pull request before merging (optional)
|
||||
- ✅ Require status checks to pass
|
||||
- ⚠️ Require review (recommended, not enforced)
|
||||
- ❌ Allow force push
|
||||
- ❌ Allow deletions
|
||||
|
||||
**Configure in Gitea:**
|
||||
Repository → Settings → Branches → Add rule
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
### Keep Branches Short-Lived
|
||||
|
||||
- Feature branches: 1-3 days max
|
||||
- Merge frequently to avoid conflicts
|
||||
- Delete after merge
|
||||
|
||||
### Sync with Develop Regularly
|
||||
|
||||
```bash
|
||||
# While on feature branch
|
||||
git checkout feature/my-feature
|
||||
git fetch origin
|
||||
git merge origin/develop
|
||||
# Resolve conflicts if any
|
||||
```
|
||||
|
||||
### Clean Commit History
|
||||
|
||||
```bash
|
||||
# Interactive rebase before PR (optional)
|
||||
git rebase -i develop
|
||||
|
||||
# Squash WIP commits into logical commits
|
||||
```
|
||||
|
||||
### Tag Releases
|
||||
|
||||
```bash
|
||||
# After merging release to main
|
||||
git checkout main
|
||||
git pull
|
||||
git tag -a v0.1.0 -m "MVP Release - Week 6"
|
||||
git push origin v0.1.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚫 Anti-Patterns (Don't Do This)
|
||||
|
||||
❌ **Commit directly to `main`**
|
||||
- Always use PR workflow
|
||||
|
||||
❌ **Long-lived feature branches**
|
||||
- Break into smaller features
|
||||
- Merge incrementally
|
||||
|
||||
❌ **Merge without review**
|
||||
- At least one other person should review
|
||||
|
||||
❌ **Push broken code to `develop`**
|
||||
- Test locally first
|
||||
- CI checks should pass
|
||||
|
||||
❌ **Forget to sync hotfix to `develop`**
|
||||
- Hotfixes must go to both branches
|
||||
|
||||
---
|
||||
|
||||
## 📊 Branch Lifecycle
|
||||
|
||||
```
|
||||
feature/barcode-scanner
|
||||
Created: 2026-02-10
|
||||
Author: Jean-Luc
|
||||
Status: In Progress
|
||||
PRs: #15 (to develop)
|
||||
|
||||
↓ (PR merged)
|
||||
|
||||
Merged to develop: 2026-02-12
|
||||
Deployed to dev: ✅
|
||||
Deleted: 2026-02-12
|
||||
```
|
||||
|
||||
**Keep branches clean:**
|
||||
```bash
|
||||
# List merged branches
|
||||
git branch --merged develop
|
||||
|
||||
# Delete merged local branches
|
||||
git branch -d feature/barcode-scanner
|
||||
|
||||
# Delete merged remote branches
|
||||
git push origin --delete feature/barcode-scanner
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Summary:** Keep it simple. Feature → PR → Develop → Test → Release → Main → Production. Always review, always test, never break `main`.
|
||||
Reference in New Issue
Block a user