DRAFT

​

Deployment Process

Our application uses a custom branching and deployment strategy with Vercel.

​

Branch Structure

• main: Source of truth, always deployable
• rc/1.XX.X: Release candidates for testing
• release/1.XX: Production releases
• stage: Used to trigger staging deployment (cona.run)
• prod: Used to trigger production deployment (cona.app)

​

Versioning

The project adheres to Semantic Versioning (SemVer) standards, with version numbers structured as MAJOR.MINOR.PATCH:

• MAJOR: Incompatible API changes
• MINOR: Backward-compatible functionality additions
• PATCH: Backward-compatible bug fixes

​

Monorepo Versioning Strategy

Our monorepo uses a simplified versioning approach:

• apps/webapp/package.json: Contains the main project version (e.g., 0.6.0)
• Internal packages (packages/*): No version fields - they’re private internal libraries
• apps/temporal-workers: Separate deployment artifact with its own version

This approach focuses version management on the main deliverable (the webapp) while keeping internal packages simple and dependency-free.

​

Environments

• Development: Automatically deployed from main (Preview deployments)
• Staging: Automatically deployed when changes are pushed to stage branch, deployed to https://cona.run
• Production: Automatically deployed when changes are pushed to prod branch, deployed to https://cona.app

​

Infrastructure Components

Each environment includes multiple components that are automatically deployed:

Web Application (Vercel)

• Staging: https://cona.run
• Production: https://cona.app

Temporal Workers (fly.io)

• Staging: Deployed using apps/temporal-workers/fly.staging.toml configuration
• Production: Deployed using apps/temporal-workers/fly.toml configuration

Database Migrations (Supabase)

• Executed via GitHub Actions with environment-specific variables
• Environment variables configured in GitHub repository settings

​

Workflow

​

Feature Development

1. Create feature branches from main
2. Merge completed features to main
3. Automatic deployment to development environment

​

Release Process

The release process is now automated through GitHub Actions, supporting three types of releases: Major, Minor, and Patch. The workflow automatically handles version bumping, branch creation, and PR generation.

Automated Release Workflow

1. Trigger the “Create RC and Release Branches” workflow from GitHub Actions
2. Select the release type:
   • Major: Increments the major version (e.g., 0.5.3 → 1.0.0)
   • Minor: Increments the minor version (e.g., 0.5.3 → 0.6.0)
   • Patch: Increments the patch version (e.g., 0.5.3 → 0.5.4)

The workflow will automatically:

• Read the current version from apps/webapp/package.json
• Calculate the next version based on the release type
• Create appropriate branches:
  • For Major/Minor: Creates rc/x.y.z from main and release/x.y from latest release
  • For Patch: Creates rc/x.y.z from the existing release branch
• Update version in apps/webapp/package.json
• Create a PR from RC to release branch

Release Testing and Deployment

1. Automatic deployment to RC Environments in Vercel (staging)
2. If issues are found in RC:
   • Fix them in main
   • Cherry-pick fixes to RC: git cherry-pick -x <commit-hash> (use -x to include the original commit message)
3. Once the RC branch is fully tested, merge the PR to the release branch

​

Hotfixes (Existing Release)

1. Trigger the “Create RC and Release Branches” workflow
2. Select “Patch” as the release type
3. The workflow will:
   • Create an RC branch from the existing release branch
   • Update the patch version in apps/webapp/package.json
   • Create a PR from RC to release branch
4. Fix any issues in main
5. Cherry-pick needed fixes to RC: git cherry-pick -x <commit-hash>
6. Once the RC branch is fully tested, merge the PR to the release branch

​

Deployment to production

Run “Create PR from latest release to prod” GitHub action to open the PR from the latest release to prod branch. Merge to prod branch automatically starts deployment to Vercel’s production environment (cona.app).

​

Testing and Fixes

1. Test the RC in staging
2. If issues are found, fix them in main
3. Cherry-pick fixes to RC: git cherry-pick -x <commit-hash>

​

Promoting to Production

​

Automated Deployment Process

Vercel (Web Application)

Automatically deployed on branch changes:

• Changes to stage branch trigger automatic deployment to https://cona.run
• Changes to prod branch trigger automatic deployment to https://cona.app

fly.io (Temporal Workers)

Automatically deployed on branch changes:

• Changes to stage branch trigger deployment using apps/temporal-workers/fly.staging.toml configuration
• Changes to prod branch trigger deployment using apps/temporal-workers/fly.toml configuration

Database Migrations (Supabase)

Executed via GitHub Actions:

• Migrations are executed automatically as part of the deployment process
• Environment-specific variables are configured in GitHub repository settings
• Supports both staging and production database environments

Note: Both Vercel and fly.io auto-deployment configurations are managed through their respective web interfaces, with GitHub integration configured to automatically deploy whenever changes are pushed to the stage or prod branches.

​

Automated Version Management

Version numbers are automatically managed through GitHub Actions workflows. Only the main project version in apps/webapp/package.json is managed - internal packages (packages/*) have no version fields and don’t require version synchronization.

​

Version Workflow

1. Creating Releases - Use the “Create RC and Release Branches” GitHub Action:

   • Automatically reads current version from apps/webapp/package.json
   • Calculates new version based on release type (Major/Minor/Patch)
   • Creates RC branch with updated version
   • Creates PR from RC to release branch

2. Automatic Version Synchronization:

   • When changes are pushed to prod branch, the “Sync Version to Main” workflow automatically runs
   • Creates a PR to sync the production version back to main branch
   • Ensures version consistency across all branches

3. Production Promotion:

   • “Create PR from latest release to prod” workflow finds the highest release branch
   • Automatically creates PR to promote to production
   • Version information is preserved throughout the process

​

Version Calculation

The automated workflows handle version bumping according to semantic versioning:

• Major: Increments major version (e.g., 1.2.3 → 2.0.0)
• Minor: Increments minor version (e.g., 1.2.3 → 1.3.0)
• Patch: Increments patch version (e.g., 1.2.3 → 1.2.4)

​

Manual Version Updates

Version updates are handled automatically by GitHub Actions. Manual version changes should be avoided to prevent conflicts with the automated system.

Note: All version management is handled through GitHub Actions workflows. The version in apps/webapp/package.json is automatically updated during the release process and synchronized across branches. Internal packages (packages/*) have no version fields and don’t require management.

​

URLs

• Staging: cona.run
• Production: cona.app