DevelopmentWorkflow.md

Development Workflow

This document covers Git workflow, branching strategy, pull requests, and CI/CD processes.

Git Workflow

OpenCashFlow uses a modified GitFlow workflow with three main environments:

Feature Branches → main → Staging → Production

Branch Types

Branch	Purpose	Naming Convention
main	Primary development branch	main
feature/*	New features	feature/add-payment-export
bugfix/*	Bug fixes	bugfix/fix-login-redirect
hotfix/*	Urgent production fixes	hotfix/security-patch
chore/*	Maintenance tasks	chore/update-dependencies
docs/*	Documentation updates	docs/update-readme

Branch Naming Rules

• Use lowercase letters
• Use hyphens to separate words
• Be descriptive but concise
• Include ticket number if applicable

Good examples:

• feature/payment-calendar-view
• bugfix/ocf-123-fix-null-reference
• chore/upgrade-dotnet-9

Bad examples:

• Feature/PaymentCalendar (wrong case)
• fix_bug (underscores, not descriptive)
• john-working-on-stuff (not descriptive)

Creating a Feature

1. Create Feature Branch

# Ensure main is up to date
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/your-feature-name

2. Make Changes

# Make your changes
# ...

# Stage changes
git add specific-files.cs

# Commit with descriptive message
git commit -m "Add payment export functionality

- Implement CSV export for payments
- Add date range filtering
- Include unit tests"

3. Keep Branch Updated

# Regularly sync with main
git fetch origin
git rebase origin/main

# Resolve any conflicts
# ...

git rebase --continue

4. Push Changes

git push origin feature/your-feature-name

Commit Guidelines

Commit Message Format

<type>: <short summary>

<optional body>

<optional footer>

Types

Type	Use Case
feat	New feature
fix	Bug fix
docs	Documentation only
style	Code style (formatting, semicolons)
refactor	Code change that neither fixes nor adds
perf	Performance improvement
test	Adding or updating tests
chore	Maintenance (deps, build, etc.)

Examples

# Simple commit
git commit -m "feat: add payment export to CSV"

# Detailed commit
git commit -m "fix: resolve null reference in payment service

The PaymentService.GetByIdAsync was throwing a NullReferenceException
when the payment was not found instead of returning null.

Fixes #123"

Commit Best Practices

1. Atomic commits - Each commit should be a single logical change
2. Present tense - "Add feature" not "Added feature"
3. No period - Don't end the summary with a period
4. 72 characters - Keep summary under 72 characters
5. Explain why - The body should explain why, not what

Pull Requests

Creating a Pull Request

1. Push your branch to GitHub
2. Navigate to the repository
3. Click "New Pull Request"
4. Select your branch as the source
5. Fill in the PR template

PR Template

## Summary
Brief description of the changes.

## Changes
- List of specific changes made
- Another change
- And another

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Screenshots (if applicable)
Include screenshots for UI changes.

## Related Issues
Closes #123

PR Checklist

Before requesting review:

• Code compiles without warnings
• All tests pass
• No unnecessary console.log/debug statements
• Code follows project conventions
• Documentation updated if needed
• Self-reviewed the diff

Code Review Process

1. Author creates PR and requests review
2. Reviewers comment on code
3. Author addresses feedback
4. Reviewers approve
5. Author merges (squash)

Review Guidelines

When reviewing:

• Focus on logic, security, and maintainability
• Ask questions rather than make demands
• Approve with minor comments if changes are optional
• Request changes for critical issues only

Merging Strategy

Squash and Merge (Default)

All PRs should be squash merged to keep history clean:

feature/add-export (5 commits) → main (1 squashed commit)

Squash Merge Benefits

• Clean, linear history
• Each commit on main is a complete feature
• Easy to revert entire features
• Clear blame history

Merge Commit (Exceptions)

Use merge commits only for:

• Merging long-lived branches
• Preserving detailed history when necessary

CI/CD Pipeline

GitHub Actions Workflows

1. Development Workflow (ci-wip-to-master.yml)

Triggered on: Push/PR to main

Steps:
1. Checkout code
2. Setup .NET 9.0
3. Restore dependencies
4. Build solution
5. Run tests

2. Staging Workflow (ci-master-to-staging.yml)

Triggered on: Tag vX.Y.Z-RC or component tags

Steps:
1. Build selected components
2. Create publish artifacts
3. Create Docker bundles
4. Create GitHub Release (prerelease)

3. Production Workflow (ci-staging-to-production.yml)

Triggered on: Stable tag vX.Y.Z

Steps:
1. Verify RC tag exists
2. Download RC artifacts (no rebuild)
3. Create production release

Tagging Convention

Tag Format	Environment	Example
vX.Y.Z-RC	Staging	v1.2.0-RC
vX.Y.Z	Production	v1.2.0
app-vX.Y.Z	App only	app-v1.2.0
api-vX.Y.Z	API only	api-v1.2.0
admin-vX.Y.Z	Admin only	admin-v1.2.0

Creating a Release

# Create RC for staging
git tag v1.2.0-RC
git push origin v1.2.0-RC

# After staging verification, create production release
git tag v1.2.0
git push origin v1.2.0

Environment Workflow

Development → Staging → Production

┌─────────────────────────────────────────────────────────────┐
│                      Development                             │
│  - Feature branches merged to main                           │
│  - Automated tests run on every PR                          │
│  - Local development with hot reload                        │
└─────────────────────────────────┬───────────────────────────┘
                                  │
                         Tag: vX.Y.Z-RC
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────┐
│                        Staging                               │
│  - Pre-release builds deployed                              │
│  - Integration testing                                       │
│  - QA verification                                          │
│  - Security scanning (OWASP ZAP)                            │
└─────────────────────────────────┬───────────────────────────┘
                                  │
                         Tag: vX.Y.Z
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────┐
│                       Production                             │
│  - Same artifacts as staging (no rebuild)                   │
│  - Monitoring active                                        │
│  - Hotfix process if issues found                           │
└─────────────────────────────────────────────────────────────┘

Hotfix Process

For critical production issues:

# Create hotfix branch from production tag
git checkout -b hotfix/critical-fix v1.2.0

# Make fix
git commit -m "fix: resolve critical security issue"

# Create new patch version
git tag v1.2.1-RC
git push origin hotfix/critical-fix v1.2.1-RC

# After staging verification
git tag v1.2.1
git push origin v1.2.1

# Merge back to main
git checkout main
git merge hotfix/critical-fix
git push origin main

Database Migrations

Migration Workflow

1. Create migration on feature branch:

   ./scripts/create-migration.sh AddNewFeature

2. Test migration locally:

   ./scripts/create-migration.sh AddNewFeature --apply

3. Include migration in PR

4. Migration runs automatically on deployment

Migration Best Practices

• Migrations should be reversible when possible
• Test both up and down migrations
• Never edit an applied migration
• Small, focused migrations over large ones

Code Style

.editorconfig

The project includes .editorconfig for consistent formatting:

[*.cs]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

Formatting Tools

# Format all C# files
dotnet format

# Check formatting without changing files
dotnet format --verify-no-changes

Testing Requirements

Before Merging

All PRs must pass:

1. Unit tests - Test individual components
2. Integration tests - Test API endpoints
3. Build verification - Solution compiles without errors

Running Tests Locally

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific project
dotnet test tests/OpenCashFlow.Test/OpenCashFlow.Test.csproj

Dependency Updates

Update Process

1. Create chore/update-dependencies branch
2. Update packages:

   dotnet outdated
   dotnet add package <PackageName> --version <NewVersion>

3. Run tests
4. Create PR with changelog of updates

Security Updates

Security updates should be:

• Applied promptly
• Tested thoroughly
• Deployed through normal CI/CD pipeline
• For critical vulnerabilities, use hotfix process

Documentation Updates

When to update documentation:

• Adding new features
• Changing existing behavior
• Updating configuration options
• Modifying API endpoints