GitHub Actions: Streamline CI/CD Workflow

Summary

This document outlines the implementation of a comprehensive Continuous Integration (CI) pipeline using GitHub Actions. This pipeline will be triggered on every push and pull request (PR). The primary goals are to ensure code quality, prevent regressions, and maintain a stable main branch. Key features include running tests across multiple Python versions, enforcing linting and type checking, measuring code coverage, and establishing quality gates before merging.

Without CI, we risk merging code that breaks the main branch.

Business Context

Problems Addressed by CI:

1. No automated testing: Currently, testing is a manual process, which is time-consuming and prone to human error. Automated testing is crucial for quickly identifying bugs and ensuring code reliability.
2. Cross-version compatibility: Testing is only performed locally, limiting compatibility checks across different Python versions. Cross-version compatibility is essential to ensure the code functions correctly in various environments.
3. Quality gates: Linters and type checkers are not consistently enforced, leading to potential code quality issues. Quality gates, such as linters and type checkers, help maintain code standards and prevent errors.
4. Coverage regression: There is no tracking of code coverage, making it difficult to identify when changes reduce test coverage. Coverage regression tracking ensures that tests adequately cover the codebase.
5. Broken main branch: Bad code can be merged, leading to instability in the main branch. Preventing a broken main branch is a top priority to maintain a stable and reliable codebase.

With CI, we ensure every commit meets quality standards, leading to a more robust and reliable software product.

Acceptance Criteria

The following criteria must be met for the CI pipeline to be considered successfully implemented:

• [x] CI runs on every push to main.
• [x] CI runs on every pull request.
• [x] Tests run on Python 3.11, 3.12, and 3.13.
• [x] Tests run on Ubuntu and macOS.
• [x] Ruff formatting/linting passes.
• [x] mypy type checking passes.
• [x] Rust clippy linting passes.
• [x] Code coverage is measured and reported.
• [x] The build completes in under 10 minutes.
• [x] Status badges are added to the README.
• [x] Failed checks block PR merge (via branch protection).

Design Doc

📄 Design Doc: GitHub Actions CI

The design document includes a comprehensive overview of the CI pipeline, including:

• Complete workflow YAML: The YAML file defines the entire CI workflow, including jobs, steps, and triggers. This ensures that the CI process is well-defined and repeatable. Having a well-structured YAML file makes it easier to manage and modify the CI process as needed.
• Job breakdown and matrix strategy: A detailed breakdown of each job within the workflow, along with the matrix strategy used for parallel execution. This allows for efficient testing across different environments and configurations. The matrix strategy optimizes resource utilization and reduces overall build time. Understanding the job breakdown is critical for troubleshooting and optimizing the CI pipeline.
• Caching strategy for fast builds: Implementation of caching mechanisms to speed up build times by reusing previously downloaded dependencies. Caching significantly reduces the time spent on downloading and installing dependencies, resulting in faster feedback cycles. This is particularly important for large projects with many dependencies.
• Cost analysis (GitHub Actions free tier): An analysis of the costs associated with running the CI pipeline on the GitHub Actions free tier. Understanding the cost implications helps ensure that the CI process remains within budget and that resources are used efficiently. This also helps in planning for future scalability and potential upgrades to paid tiers if necessary.
• Implementation plan: A step-by-step plan for implementing the CI pipeline, including timelines and responsibilities. This ensures that the implementation process is well-organized and that progress can be tracked effectively. Having a clear implementation plan helps minimize delays and ensures that the CI pipeline is set up correctly.

Workflow Jobs

The CI workflow consists of three primary jobs:

Job 1: Test Matrix

Matrix: Python 3.11/3.12/3.13 × Ubuntu/macOS

Steps: Checkout, Setup Rust/Python, Build, Test, Upload Coverage

This job focuses on running tests across a matrix of Python versions and operating systems. The Test Matrix job is crucial for ensuring that the code functions correctly in different environments. It involves checking out the code, setting up the necessary Rust and Python environments, building the project, running tests, and uploading coverage data to Codecov. This job provides comprehensive feedback on the code's compatibility and reliability across various platforms.

Job 2: Lint Python

Steps: Format check, Lint, Import check, Type check

This job is responsible for linting and type checking the Python code. The Lint Python job ensures that the code adheres to coding standards and best practices. It involves performing format checks, running linters, checking imports, and performing type checking using mypy. This job helps maintain code quality, prevent errors, and improve the overall maintainability of the codebase. By enforcing consistent coding styles and catching potential type errors early, this job contributes to a more robust and reliable software project.

Job 3: Lint Rust

Steps: Format check, Clippy

This job focuses on linting the Rust code. The Lint Rust job ensures that the Rust code adheres to coding standards and best practices. It involves performing format checks and running Clippy, a Rust linter. This job helps maintain code quality, prevent errors, and improve the overall maintainability of the codebase. By enforcing consistent coding styles and catching potential issues early, this job contributes to a more robust and reliable software project.

Implementation Plan

See the complete implementation plan in: docs/design/github-actions-ci.md

Phase 1: Setup Infrastructure (Codecov)

Phase 2: Implement Test Job

Phase 3: Add Linting Jobs

Phase 4: Add Coverage

Phase 5: Branch Protection

Phase 6: Optimize

Definition of Done

The following criteria must be met for the implementation to be considered complete:

• [x] .github/workflows/ci.yml created
• [x] CI runs on push to main
• [x] CI runs on pull requests
• [x] Test matrix runs (6 jobs: 3 Python × 2 OS)
• [x] Lint jobs run (Python + Rust)
• [x] Coverage uploads to Codecov
• [x] Status badges added to README
• [x] Branch protection enabled on main
• [x] All checks pass on main branch
• [x] Documentation updated
• [x] Design doc approved

Estimated Effort

1 day

• 2 hours: Create workflow file
• 2 hours: Setup Codecov
• 1 hour: Test and debug
• 1 hour: Setup branch protection
• 2 hours: Optimize and document

Dependencies

Blocked by:

• Issue #19 (Singleton Caching Bug) - Tests must pass first

Blocks:

• Issue #23 (Release Workflow) - Needs working CI

For more information about GitHub Actions, visit the official GitHub Actions documentation.