z3/.github/workflows/CI_TESTING.md

Testing the CI Workflow

This document provides instructions for testing the new GitHub Actions CI workflow after migration from Azure Pipelines.

Quick Test

To test the workflow:

1. Push a branch or create a PR: The workflow automatically triggers on all branches
2. View workflow runs: Go to the "Actions" tab in GitHub
3. Monitor progress: Click on a workflow run to see job details

Manual Trigger

You can also manually trigger the workflow:

1. Go to the "Actions" tab
2. Select "CI" from the left sidebar
3. Click "Run workflow"
4. Choose your branch
5. Click "Run workflow"

Local Validation

Before pushing, you can validate the YAML syntax locally:

# Using yamllint (install with: pip install yamllint)
yamllint .github/workflows/ci.yml

# Using Python PyYAML
python3 -c "import yaml; yaml.safe_load(open('.github/workflows/ci.yml'))"

# Using actionlint (install from https://github.com/rhysd/actionlint)
actionlint .github/workflows/ci.yml

Job Matrix

The CI workflow includes these job categories:

Linux Jobs

• linux-python-debug: Python-based build with make (MT and ST variants)
• manylinux-python-amd64: Python wheel build for manylinux AMD64
• manylinux-python-arm64: Python wheel build for manylinux ARM64 (cross-compile)
• ubuntu-ocaml: OCaml bindings build
• ubuntu-ocaml-static: OCaml static library build
• ubuntu-cmake: CMake builds with multiple compilers (4 variants)

macOS Jobs

• macos-python: Python-based build with make
• macos-cmake: CMake build with Julia support

Expected Runtime

Approximate job durations:

• Linux Python builds: 20-30 minutes
• Manylinux Python builds: 15-25 minutes
• OCaml builds: 25-35 minutes
• CMake builds: 25-35 minutes each variant
• macOS builds: 30-40 minutes

Total workflow time (all jobs in parallel): ~40-60 minutes

Debugging Failed Jobs

If a job fails:

1. Click on the failed job to see the log

2. Expand failed steps to see detailed output

3. Check for common issues:

   • Missing dependencies
   • Test failures
   • Build errors
   • Timeout (increase timeout-minutes if needed)

4. Re-run failed jobs:

   • Click "Re-run failed jobs" button
   • Or "Re-run all jobs" to test everything

Comparing with Azure Pipelines

To compare results:

1. Check the last successful Azure Pipelines run
2. Compare job names and steps with the GitHub Actions workflow
3. Verify all tests pass with similar coverage

Differences from Azure Pipelines

1. Checkout: Explicit actions/checkout@v4 step (was implicit)
2. Python Setup: Explicit actions/setup-python@v5 step (was implicit)
3. Template Files: Inlined instead of external templates
4. Artifacts: Uses actions/upload-artifact (if needed in future)
5. Caching: Can add actions/cache for dependencies (optional optimization)

Adding Jobs or Modifying

To add or modify jobs:

1. Edit .github/workflows/ci.yml
2. Follow the existing job structure
3. Use matrix strategy for variants
4. Add appropriate timeouts (default: 90 minutes)
5. Test your changes on a branch first

Optimization Opportunities

Future optimizations to consider:

1. Caching: Add dependency caching (npm, pip, opam, etc.)
2. Artifacts: Share build artifacts between jobs
3. Concurrency: Add concurrency groups to cancel outdated runs
4. Selective Execution: Skip jobs based on changed files
5. Self-hosted Runners: For faster builds (if available)

Rollback Plan

If the GitHub Actions workflow has issues:

1. The original azure-pipelines.yml is still in the repository
2. Azure Pipelines can be re-enabled if needed
3. Both systems can run in parallel during transition

Support

For issues or questions:

1. Check GitHub Actions documentation: https://docs.github.com/en/actions
2. Review the migration document: .github/workflows/CI_MIGRATION.md
3. Check existing GitHub Actions workflows in .github/workflows/
4. Open an issue in the repository