|
| 1 | +# GitHub Workflows for svMultiPhysics |
| 2 | + |
| 3 | +This directory contains GitHub Actions workflows that run various actions (tests, checks, docker builds, documentation, code coverage assessment) on the repository. These workflows are run whenever new code is added to the repository, either upon push to a fork of svMultiPhysics, or upon a pull request to SimVascular/svMultiPhysics. Upon pull request, these actions must succeed for pull request to be merged. |
| 4 | + |
| 5 | +## Workflows |
| 6 | + |
| 7 | +### 1. Tests Workflow (`workflows/tests.yml`) |
| 8 | + |
| 9 | +**Purpose**: Runs comprehensive integration tests on both Ubuntu and macOS platforms when relevant code changes are detected. The integration tests can be found in the `tests/` directory and use `pytest`. |
| 10 | + |
| 11 | +**Triggers**: |
| 12 | +- Pull requests |
| 13 | +- Pushes to any branch |
| 14 | + |
| 15 | +**Key Features**: |
| 16 | +- **Smart Change Detection**: Only runs full test suite when changes are made to important directories (`Code/`, `tests/`, `.github/`) |
| 17 | +- **Multi-Platform Testing**: Runs tests on both Ubuntu (using Docker container) and macOS |
| 18 | +- **Coverage Reporting**: Generates and uploads code coverage reports to Codecov |
| 19 | + |
| 20 | +**Jobs**: |
| 21 | +1. `check-for-changes`: Determines if full test suite should run based on file changes in important directories. Uses `dorny/paths-filter@v3` to filter directories. |
| 22 | +2. `test-ubuntu`: Runs tests in Ubuntu environment through `actions/test-ubuntu/action.yml`. Triggered only if `check-for-changes` returns `run_full_tests = true` |
| 23 | +3. `test-macos`: Runs tests on macOS through `actions/test-macos/action.yml`. Triggered only if `check-for-changes` returns `run_full_tests = true` |
| 24 | +4. `all-tests`: Coordinates test results for branch protection rules. If `test-ubuntu` and `test-macos` run, returns success status only if both `test-ubuntu` and `test-macos` return success. If `test-ubuntu` and `test-macos` are skipped, always returns success. This test must pass for a pull request to be merged, as set by branch protection rules. |
| 25 | + |
| 26 | +### 2. Docker Solver Build Workflow (`workflows/docker_solver_build.yml`) |
| 27 | + |
| 28 | +**Purpose**: Builds and publishes Docker images for the solver component. |
| 29 | + |
| 30 | +**Triggers**: |
| 31 | +- Pushes to the `main` branch |
| 32 | + |
| 33 | +**Process**: |
| 34 | +1. Sets up QEMU and Docker Buildx for multi-platform builds |
| 35 | +2. Authenticates with DockerHub using stored credentials |
| 36 | +3. Builds the Docker image using `Docker/solver/dockerfile` |
| 37 | +4. Pushes the image to `simvascular/solver:latest` |
| 38 | + |
| 39 | +### 3. Documentation Workflow (`workflows/documentation.yml`) |
| 40 | + |
| 41 | +**Purpose**: Builds and deploys HTML documentation using Doxygen. |
| 42 | + |
| 43 | +**Triggers**: |
| 44 | +- All pushes and pull requests |
| 45 | + |
| 46 | +**Process**: |
| 47 | +1. Installs Doxygen |
| 48 | +2. Generates documentation from `Documentation/Doxyfile` |
| 49 | +3. Uploads documentation as an artifact |
| 50 | +4. Deploys documentation to GitHub Pages (only for `main` branch) |
| 51 | + |
| 52 | +### 4. Copyright Workflow (`workflows/copyright.yml`) |
| 53 | + |
| 54 | +**Purpose**: Ensures all source files contain proper copyright headers. |
| 55 | + |
| 56 | +**Triggers**: |
| 57 | +- All pushes and pull requests |
| 58 | + |
| 59 | +**Process**: |
| 60 | +- Uses `kt3k/license_checker` to verify copyright headers in `.h` and `.cpp` files |
| 61 | +- Fails the workflow if any files are missing proper copyright notices |
| 62 | + |
| 63 | +## Testing Actions |
| 64 | + |
| 65 | +### 1. Test Ubuntu Action (`actions/test-ubuntu/action.yml`) |
| 66 | + |
| 67 | +**Purpose**: Comprehensive integration testing on Ubuntu with code coverage. |
| 68 | + |
| 69 | +**Environment**: Uses `simvascular/libraries:ubuntu22` Docker container |
| 70 | + |
| 71 | +**Steps**: |
| 72 | +1. **Build svZeroDSolver**: Clones and builds the ZeroD solver dependency |
| 73 | +2. **Build svMultiPhysics (Trilinos)**: Builds with Trilinos support, coverage, and unit tests enabled |
| 74 | +3. **Build svMultiPhysics (PETSc)**: Builds with PETSc support as an alternative |
| 75 | +4. **Run Integration Tests**: Executes pytest tests in the `tests/` directory |
| 76 | +5. **Run Unit Tests**: Executes CTest unit tests |
| 77 | +6. **Generate Coverage**: Creates coverage reports |
| 78 | +7. **Upload Coverage**: Sends coverage data to Codecov |
| 79 | + |
| 80 | +### 2. Test macOS Action (`actions/test-macos/action.yml`) |
| 81 | + |
| 82 | +**Purpose**: Comprehensive testing on macOS with native dependencies. |
| 83 | + |
| 84 | +**Steps**: |
| 85 | +1. **Install Dependencies**: Uses Homebrew to install GCC, VTK, OpenBLAS, LAPACK, Mesa, OpenMPI, Qt, and lcov |
| 86 | +2. **Install Miniconda**: Sets up Python environment |
| 87 | +3. **Build svZeroDSolver**: Clones and builds the ZeroD solver |
| 88 | +4. **Build svMultiPhysics**: Builds with coverage and unit tests enabled |
| 89 | +5. **Install Test Dependencies**: Creates conda environment with Python testing libraries |
| 90 | +6. **Run Integration Tests**: Executes pytest tests |
| 91 | +7. **Run Unit Tests**: Executes CTest unit tests |
| 92 | + |
| 93 | +## Configuration Files |
| 94 | + |
| 95 | +### Codecov Configuration (`codecov.yml`) |
| 96 | + |
| 97 | +Configures code coverage reporting with Codecov: |
| 98 | +- Sets coverage status to "informational" for both project and patch coverage |
| 99 | +- This means coverage reports won't block PRs but provide visibility into test coverage |
| 100 | + |
| 101 | +## Usage |
| 102 | + |
| 103 | +### For Contributors |
| 104 | + |
| 105 | +1. **Making Changes**: When you push changes or create a pull request, the workflows will automatically run |
| 106 | +2. **Test Requirements**: Ensure your changes don't break existing tests |
| 107 | +3. **Copyright**: Make sure all new `.h` and `.cpp` files include proper copyright headers |
| 108 | +4. **Documentation**: Update documentation if you add new features |
| 109 | + |
| 110 | +### For Maintainers |
| 111 | + |
| 112 | +1. **Branch Protection**: [Branch protection rules](https://github.com/SimVascular/svMultiPhysics/settings/branch_protection_rules/36012339) require successes from the following checks in order for a pull request to be merged. |
| 113 | + 1. "check-license-lines" in `copyright.yml` |
| 114 | + 2. "documentation" in `documentation.yml` |
| 115 | + 3. "All Tests" in `tests.yml` |
| 116 | +2. **Docker Releases**: Docker images are automatically built and pushed when changes are merged to `main` |
| 117 | +3. **Documentation**: Documentation is automatically deployed to GitHub Pages from the `main` branch |
| 118 | + |
| 119 | +## Dependencies |
| 120 | + |
| 121 | +### Required Secrets |
| 122 | + |
| 123 | +The workflows require the following secrets to be configured in the repository settings: |
| 124 | + |
| 125 | +- `CODECOV_TOKEN`: Token for uploading coverage reports to Codecov |
| 126 | +- `DOCKER_PASSWORD`: Password for DockerHub authentication |
| 127 | +- `GITHUB_TOKEN`: Automatically provided by GitHub for documentation deployment |
0 commit comments