Skip to content

⚙️ The Apollyon Engineering Workflow

To build fail-safe safety infrastructure, our code delivery pipeline must be as resilient as our hardware. This document outlines the exact lifecycle of a line of code at Apollyon—from your local IDE to the production server.

The Golden Rule

Nobody pushes directly to main. Ever. All code reaches production exclusively through a reviewed and approved Merge Request (MR).

1. Branching Strategy

We use a simplified GitLab Flow. The main branch is sacred; it must always mirror exactly what is running on our production servers.

When you pick up a ticket, create a new branch from main using the following prefix conventions:

  • feat/... : Adding a new feature (e.g., feat/whatsapp-webhook)
  • fix/... : Fixing a bug in production (e.g., fix/fastapi-cors-error)
  • docs/... : Updating this handbook or API swagger docs (e.g., docs/add-esp32-pinout)
  • hw/... : Hardware/firmware specific changes (e.g., hw/update-voice-assistant-ota)
  • chore/... : Maintenance tasks like updating dependencies (e.g., chore/bump-pydantic-version)

2. Local Development & Parity

Because our team uses different operating systems, Docker is our source of truth.

  1. Never run bare-metal installations. Do not use pip install or npm install directly on your host machine to run a service.
  2. Use Docker Compose. Every software project (like the Korvy backend) includes a docker-compose.dev.yml file. Spin up the entire stack locally using docker compose -f docker-compose.dev.yml up -d.
  3. Database Migrations: Never manually alter your local database schema using raw SQL commands. If you need a new column, generate a migration script (e.g., using Alembic for Python). The CI/CD pipeline will automatically run this script on the production database during deployment.

3. Commit Message Standards

We strictly adhere to the Conventional Commits standard. This allows us to quickly read git log histories and eventually automate our release notes.

Format: <type>(<optional scope>): <description>

Examples: * ✅ feat(api): add user authentication endpoint * ✅ fix(db): resolve connection timeout on heavy load * ✅ docs(handbook): update engineering workflow * ❌ fixed the bug (Rejected: Unclear type and description) * ❌ update code (Rejected: Unclear intent)

4. The Definition of Done (DoD)

Before you mark a Merge Request as "Ready for Review," it must meet the Apollyon Definition of Done. Reviewers will reject MRs that do not check all of these boxes.

  • [ ] Pipeline Passes: The GitLab CI/CD pipeline is green (all linting, formatting, and automated tests pass).
  • [ ] Peer Reviewed: The code has been reviewed and approved by at least one other engineer.
  • [ ] Migrations Included: Any database schema changes include the corresponding automated migration script.
  • [ ] Documentation Updated: If you changed an API endpoint, the Swagger/OpenAPI docs are updated. If you changed a physical hardware setup, the wiki is updated.
  • [ ] No Hardcoded Secrets: No .env variables, API tokens, or passwords are hardcoded in the committed files.

5. Deployment

Once an MR is approved and merged into main, the Apollyon GitLab Runner takes over.

  1. The Runner SSHs into the production Ubuntu server.
  2. It pulls the latest main branch.
  3. It rebuilds the Docker images.
  4. It executes any pending database migrations.
  5. It safely restarts the affected containers with zero downtime.

If a deployment fails, the pipeline will alert the #engineering channel in Mattermost.