> ## Documentation Index
> Fetch the complete documentation index at: https://cona.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment Process

> How we deploy our application

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](https://semver.org/spec/v2.0.0.html) (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](https://cona.run)
* Changes to `prod` branch trigger automatic deployment to [https://cona.app](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`