Skip to content
Dice Chess Lab

Development Workflow

This guide documents the engineering standards and automated pipelines that ensure the stability and quality of the Dice Chess Trainer.

Git Workflow

Section titled “Git Workflow”

We use a feature-branch workflow. All changes must be made in dedicated branches and merged into the main branch via Pull Requests.

Branch Naming Conventions

Section titled “Branch Naming Conventions”

To keep our repository organized and linked to issues, we follow a strict naming convention:

  • task/[ID]-[brief-description] — For general tasks and refactorings (e.g., task/365-dev-docs).
  • feat/[ID]-[feature-name] — For new features (e.g., feat/361-no-legal-moves).
  • bug/[ID]-[fix-description] — For bug fixes.

Lifecycle of a Change

Section titled “Lifecycle of a Change”
gitGraph
    commit id: "Initial"
    branch "feat/361-no-legal-moves"
    checkout "feat/361-no-legal-moves"
    commit id: "Implementation"
    commit id: "Tests"
    checkout main
    merge "feat/361-no-legal-moves" id: "PR #362" tag: "v0.12.0"
    branch "task/365-dev-docs"
    checkout "task/365-dev-docs"
    commit id: "Mermaid diagrams"

CI/CD Pipeline

Section titled “CI/CD Pipeline”

Our deployment process is automated and gated by multiple quality checks. The primary goal is to ensure that no broken build ever reaches the production server.

Pipeline Overview

Section titled “Pipeline Overview”

The following diagram illustrates how a code change travels from a Git tag to the production Raspberry Pi.

flowchart TD
    A[Ops: Release] -- "Creates Git Tag" --> B[CD: Staging Deploy]
    subgraph Staging_RPi3 ["Staging Host (RPi 3)"]
        B -- "1. Build ARM64 Image" --> C[Push to GHCR]
        C -- "2. Pull & Run" --> D[Verify Health]
        D -- "3. Run E2E Tests" --> E{Tests Pass?}
    end
    E -- "Yes" --> F[CD: Production Deploy]
    E -- "No" --> G[Block Production & Alert]
    subgraph Production_RPi4 ["Production Host (RPi 4)"]
        F -- "Pull & Run" --> H[Live App]
    end

    style Staging_RPi3 fill:#f9f,stroke:#333,stroke-width:2px
    style Production_RPi4 fill:#bbf,stroke:#333,stroke-width:2px
    style E fill:#fff,stroke:#f00,stroke-width:4px

Safety Gates

Section titled “Safety Gates”
  1. Staging-First: No code is deployed to production without first being deployed to the staging environment (RPi 3).
  2. E2E Gating: The production deployment workflow is triggered only after the Staging Deploy workflow completes successfully. Since Staging Deploy includes a mandatory Playwright E2E test suite, any test failure automatically blocks the production release.
  3. Cross-Compilation: All images are built on high-performance GitHub runners to avoid OOM crashes on the low-RAM Raspberry Pi devices.

Local Development Flow

Section titled “Local Development Flow”

Before pushing code, developers (and AI agents) are expected to:

  1. Lint & Format: Run mise run check (monorepo global) or mise run backend:check.
  2. Unit Tests: Ensure all business logic is covered by Vitest or Pytest.
  3. Implementation Plan: For complex tasks, create an implementation_plan.md and obtain user approval before writing code.