Release Process

How to prepare and ship releases for the CPR backend.

Pre-Release Checklist

Before releasing:

• [ ] All tests pass (composer test)
• [ ] Static analysis passes (composer stan)
• [ ] Code is formatted (composer pint --test)
• [ ] Database migrations are tested (php artisan migrate:fresh --seed)
• [ ] API documentation is up to date (Scramble auto-generates from code)
• [ ] Environment variables are documented if new ones were added
• [ ] Breaking changes are documented

Release Flow

1. Prepare the Release

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

# Run full test suite
composer test

# Verify static analysis
composer stan

2. Tag the Release

# Create annotated tag
git tag -a v1.x.x -m "Release v1.x.x: description"

# Push the tag
git push origin v1.x.x

3. Deploy

Follow the Deployment Guide to deploy the tagged release.

4. Post-Release Verification

• Verify the application is running (GET /api/v1/public/health)
• Check Sentry for any new errors
• Verify database migrations ran successfully
• Test critical flows (login, patient creation, queue operations)

Hotfix Process

For urgent production fixes:

# Branch from master
git checkout -b fix/urgent-issue master

# Make the fix, test it
composer test

# Merge directly to master
git checkout master
git merge fix/urgent-issue

# Tag and deploy
git tag -a v1.x.x -m "Hotfix: description"
git push origin master --tags

Database Migration Considerations

When a release includes database migrations:

1. Always test migrations against a copy of production data before deploying
2. Migrations should be reversible - Implement the down() method
3. Avoid destructive migrations in production (dropping columns/tables) without a backup plan
4. Large data migrations should be done in a maintenance window

API Versioning

The API is versioned under /api/v1/. If breaking changes are needed:

1. Create new route files under routes/api/v2/
2. Create new controllers in app/Http/Controllers/Api/V2/
3. Keep v1 endpoints functional during the transition period
4. Communicate deprecation timeline to frontend teams