1. Development Process and CI/CD Pipeline#

This document outlines the branching strategy, development workflow, and GitHub Actions CI/CD pipeline used in the project to maintain code quality and streamline deployment.

1.1. Branching Strategy#

The project follows a structured branching strategy to separate development, staging, and production environments:

  • feature branches Branch**: Each feature or fix is developed in its own branch, prefixed with “feature” (e.g., feature_123). This branch is where individual developers work until the feature is ready for testing.

  • dev: The main development branch where validated feature branches are merged. It serves as an integration branch for all features under development.

  • alpha: A pre-release or staging branch that reflects a stable version of dev. Once dev reaches a stable point, it is merged into alpha for final testing before production.

  • master: The production branch. Only stable and fully tested code is merged here, and this branch is automatically deployed to PyPI upon tagging.

1.2. Pushes and Merge Workflow#

  1. Feature Branch Development:

    • Each developer creates a featureXXX branch to work on their feature.

    • When the feature is complete, a pull request (PR) is made to merge featureXXX into dev.

    • GitHub Actions will automatically run tests and generate a coverage report on the PR.

    • If the tests pass, the feature can be merged into dev; if tests fail, the PR cannot be merged until issues are resolved.

  2. Development Integration on `dev`:

    • Multiple featureXXX branches may be merged into dev concurrently.

    • This branch is intended for integrating and testing new features collectively before staging.

    • When dev reaches a stable state with passing tests, it can proceed to the alpha branch.

  3. Alpha Testing on `alpha`:

    • The dev branch is merged into alpha for pre-release validation.

    • GitHub Actions re-runs tests and generates a coverage report to verify stability.

    • If all tests pass, the version is tagged on alpha, marking it as ready for release.

    • Build and installation tests are also performed to ensure the package can be installed correctly.

  4. Production Release on `master`:

    • The fully tested and working code is merged into master.

    • The version is tagged on master to mark it as a stable release.

    • Once there is a tag, a release is created on GitHub, documenting the changes.

    • The released version is automatically published to PyPI, making the package available to users.

1.3. GitHub Actions CI/CD Pipelines#

The project utilizes four primary GitHub Actions workflows:

  1. Feature Branch Validation:

    • Workflow File: code_quality.yml

    • Trigger: Initiates on pull requests targeting the dev branch from feature branches (e.g., featureXXX).

    • Functionality:

      • Runs static code analysis using Qodana.

      • Ensures code quality and standards compliance before merging.

      • Executes within an isolated environment to verify quality without modifying the branch.

      • Validates that the code aligns with development standards before it can be integrated into dev.

  2. Alpha Branch Validation:

    • Workflow Files: CI.yml and build-test-package.yml

    • Trigger: Runs on any push to the alpha branch.

    • Functionality:

      • Executes tests across different Python versions to ensure compatibility.

      • Uploads test coverage reports to Codecov, maintaining accountability for test quality.

      • Builds the package, installs it in a virtual environment, and runs tests to confirm the package’s standalone functionality.

      • Acts as the final pre-production gate, validating that alpha is stable before being merged into master.

  3. Production Release to PyPI:

    • Workflow File: publish-to-pypi.yml

    • Trigger: Executes upon tagged releases to master.

    • Functionality:

      • Builds the package into source and wheel distributions.

      • Publishes the package to PyPI, ensuring the release is available in production.

      • This workflow guarantees that only a stable, tested, and tagged version is deployed to PyPI.

  4. Build and Install Test for Package Validation:

    • Workflow File: build-test-package.yml

    • Trigger: Activates on any push or pull request to alpha.

    • Functionality:

      • Builds the package and verifies that it can be installed in an isolated environment.

      • Ensures the package can run independently of the source, verifying import dependencies and package structure.

      • Provides confidence that the package can be distributed and used without issues related to build or installation.

By following this CI/CD strategy, the project maintains high code quality, consistent testing, and reliable releases with minimal manual intervention.