🔄 Git Workflow & Versioning

📋 Overview

LIPAIX follows a trunk-based development approach, where the main branch is the single source of truth and all deployments flow from it. This approach ensures consistency, reduces merge conflicts, and enables rapid, reliable deployments.

🏗️ Branching Strategy

Main Branch (Trunk)

The main branch is our production-ready codebase:

• 🚀 Always Deployable - Every commit to main is production-ready
• 🔄 Continuous Integration - Automated testing on every push
• 📦 Source of Truth - All deployments originate from main
• 🔒 Protected - No direct pushes, only via pull requests

Branching Strategy Diagram

main:     ●────────●────────●────────●────────●
           │        │        │        │        │
           │        │        │        │        │
feature1:  │        └──●─────●        │        │
           │             │    │        │        │
           │             │    │        │        │
feature2:  │             │    │        └──●─────●
           │             │    │             │    │
           │             │    │             │    │
           │             │    │             │    │
           ▼             ▼    ▼             ▼    ▼
        Initial    Auth   Tests   Merge   Dashboard  Merge
        Commit     Feature        to Main  Feature   to Main

Legend:

• ● = Commit
• ─ = Branch timeline
• │ = Branch connection
• ▼ = Merge point

Feature Branches

Short-lived branches for feature development:

# Create a feature branch
git checkout -b feature/user-authentication

# Develop and commit changes
git add .
git commit -m "feat: implement user authentication system"

# Push to remote
git push origin feature/user-authentication

# Create pull request to merge into main

Release Branches

Temporary branches for release preparation:

# Create release branch from main
git checkout -b release/v1.2.0

# Make release-specific adjustments
git commit -m "chore: bump version to 1.2.0"

# Merge to main and tag
git checkout main
git merge release/v1.2.0
git tag v1.2.0

# Delete release branch
git branch -d release/v1.2.0

🔄 Development Workflow

1. Feature Development

# Start new feature
git checkout main
git pull origin main
git checkout -b feature/new-feature

# Develop feature
# ... make changes ...

# Commit with conventional commits
git commit -m "feat: add new user dashboard"
git commit -m "fix: resolve authentication bug"
git commit -m "docs: update API documentation"

2. Pull Request Process

# Push feature branch
git push origin feature/new-feature

# Create pull request on GitHub
# - Title: "feat: add new user dashboard"
# - Description: Detailed explanation of changes
# - Assign reviewers
# - Link related issues

3. Code Review & Merge

• Automated Checks - CI/CD pipeline validation
• Code Review - Peer review and approval
• Merge Strategy - Squash and merge to maintain clean history
• Deployment - Automatic deployment to Railway

📝 Conventional Commits

We follow the Conventional Commits specification:

Commit Types

feat:     # New feature
fix:      # Bug fix
docs:     # Documentation changes
style:    # Code style changes (formatting, etc.)
refactor: # Code refactoring
test:     # Adding or updating tests
chore:    # Maintenance tasks

Commit Examples

feat(auth): implement OAuth2 authentication
fix(api): resolve user data validation issue
docs(readme): update installation instructions
style(ui): improve button component styling
refactor(core): extract common utilities
test(auth): add authentication test suite
chore(deps): update dependencies

🏷️ Version Management

Semantic Versioning

We follow Semantic Versioning (MAJOR.MINOR.PATCH):

• MAJOR - Breaking changes, incompatible API changes
• MINOR - New features, backward-compatible additions
• PATCH - Bug fixes, backward-compatible patches

Version Bumping

# Patch version (bug fixes)
git commit -m "fix: resolve login issue"
# Version: 1.2.0 → 1.2.1

# Minor version (new features)
git commit -m "feat: add user profile management"
# Version: 1.2.1 → 1.3.0

# Major version (breaking changes)
git commit -m "feat!: redesign authentication API"
# Version: 1.3.0 → 2.0.0

🔧 Git Configuration

Recommended Settings

# Global Git configuration
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Enable signing commits (optional but recommended)
git config --global commit.gpgsign true

# Set default branch name
git config --global init.defaultBranch main

# Configure line ending handling
git config --global core.autocrlf input  # macOS/Linux
git config --global core.autocrlf true   # Windows

Git Hooks

We use Git hooks for code quality:

# Pre-commit hooks
- Lint code with ESLint
- Format code with Prettier
- Run unit tests
- Check commit message format

# Pre-push hooks
- Run full test suite
- Build verification
- Security scanning

🚀 Deployment Integration

Automatic Deployments

Every merge to main triggers:

1. Automated Testing - Full test suite execution
2. Build Verification - Ensure code compiles and builds
3. Security Scanning - Vulnerability and dependency checks
4. Deployment - Automatic deployment to Railway
5. Health Checks - Verify deployment success

Deployment Branches

Railway automatically deploys from main:

• Main Branch → Production environment
• Feature Branches → Preview environments (optional)
• Release Branches → Staging environment (optional)

📊 Best Practices

Do's

• ✅ Keep branches short-lived - Merge within 1-2 days
• ✅ Use descriptive branch names - feature/user-dashboard
• ✅ Write clear commit messages - Follow conventional commits
• ✅ Review code thoroughly - Don't rush merges
• ✅ Test before merging - Ensure CI passes

Don'ts

• ❌ Don't work directly on main - Always use feature branches
• ❌ Don't merge broken code - Fix issues before merging
• ❌ Don't skip code reviews - Peer review is mandatory
• ❌ Don't force push to main - Use pull requests
• ❌ Don't ignore CI failures - Fix build issues first

🚀 Deployment Process

⚠️ IMPORTANT: Deployment is MANUAL, not automatic!

Manual Deployment Workflow

1. Feature Development → Feature branch
2. Code Review → Pull Request to main
3. Merge to Main → ✅ Code is in main (but NOT deployed)
4. Manual Deployment → 👤 Trigger GitHub Actions workflow
5. Deployment Branch Update → deploy/web or deploy/staging/web
6. Railway Deployment → 🚂 Service updates

Key Points

• ❌ Merging to main does NOT deploy automatically
• ✅ Deployment requires manual action via GitHub Actions
• 🔧 Separate deployment branches for staging and production
• 📋 Manual approval for each deployment

The main branch is our source of truth for code, but deployment happens manually through separate deployment branches.