Skip to content

code-reading-guide.md

Latest commit

 

History

History
129 lines (102 loc) · 6.07 KB

code-reading-guide.md

File metadata and controls

129 lines (102 loc) · 6.07 KB
Raw

Code Reading Guide

If a term is unfamiliar, check the shared glossary first: docs/glossary.md

Repository Layout

Containerfile                         native image build definition
build_files/build-image.sh            build-time orchestration inside the image
containerfiles/zfs-akmods/            compose-time ZFS install helper
shared/                               shared Python helpers copied into CI and image build context
ci/defaults.json                      checked-in defaults shared by workflows and helpers
files/scripts/                        image-local helper scripts
ci_tools/                             workflow helper commands
.github/actions/                      local composite actions used by the workflows
.github/workflows/                    GitHub Actions pipelines
.github/scripts/README.md             workflow step -> command-line interface (CLI) command map
docs/                                 teaching-style documentation

Core Workflows

  • .github/workflows/build.yml
    • main push/schedule/manual workflow
    • candidate-first build and promotion
    • scheduled runs skip when the upstream Aurora base image has not advanced since the last promoted image (see "Safety Model" above)
  • .github/workflows/build-branch.yml
    • branch-tagged test builds
    • reuse or rebuild the shared akmods cache when the branch targets a new primary kernel
  • .github/workflows/build-pr.yml
    • pull request (PR) validation build
    • no push and no signing
  • .github/workflows/test.yml
    • Python unit tests and ruff lint for all CI tool modules
    • runs on pull requests and pushes to main

Docs-only changes do not trigger image builds.

Read This Repo In This Order

1. Main workflow

2. Command map and command-line interface (CLI)

3. Input resolution and cache checks

  1. ci_tools/resolve_build_inputs.py
  2. ci_tools/write_build_inputs_manifest.py
  3. ci_tools/check_akmods_cache.py
  4. ci_tools/prepare_validation_build.py
    • pull-request cache validation plus pinned-akmods-ref fetch validation
  5. ci_tools/tagging_context.py
    • normalizes registry paths and detects automation accounts

4. Akmods build control

  1. ci_tools/akmods_clone_pinned.py
    • clones the resolved upstream akmods commit and verifies the exact SHA
  2. ci_tools/akmods_configure_zfs_target.py
  3. ci_tools/akmods_build_and_publish.py

5. Native image composition

  1. Containerfile
  2. build_files/build-image.sh
  3. files/scripts/configure_signing_policy.py
  4. containerfiles/zfs-akmods/install_zfs_from_akmods_cache.py
  5. shared/oci_layout.py

6. Tagging and signing

  1. ci_tools/tagging_context.py
    • builds candidate tags, branch tags, branch-safe prefixes, and registry context values
  2. ci_tools/promote_stable.py
  3. ci_tools/sign_image.py
    • used by branch/main publish flows; publication requires SIGNING_SECRET
  4. .github/actions/
    • local composite actions used to keep the workflow files readable

7. Failure triage

  1. .github/workflows/akmods-failure-triage.yml
    • opens or updates sticky GitHub issues for classified akmods build failures
  2. ci_tools/classify_akmods_failure.py
    • turns akmods build logs into a small issue payload for the triage workflow

8. Tests

  1. tests/test_akmods_build_and_publish.py
  2. tests/test_akmods_clone_pinned.py
  3. tests/test_akmods_configure_zfs_target.py
  4. tests/test_check_akmods_cache.py
  5. tests/test_classify_akmods_failure.py
  6. tests/test_cli.py
  7. tests/test_common.py
  8. tests/test_configure_signing_policy.py
  9. tests/test_export_repo_defaults.py
  10. tests/test_install_zfs_from_akmods_cache.py
  11. tests/test_prepare_validation_build.py
  12. tests/test_promote_stable.py
  13. tests/test_resolve_build_inputs.py
  14. tests/test_sign_image.py
  15. tests/test_tagging_context.py
  16. tests/test_write_build_inputs_manifest.py

Running Tests

pip install pytest pytest-cov pyyaml
python3 -m pytest tests/ -v

Tests use unittest.TestCase with unittest.mock.patch and have no external dependencies beyond pytest as the test runner (pyyaml is installed so the YAML-schema tests run instead of skipping; pytest-cov feeds the coverage floors). Every CI tool module in ci_tools/ has a corresponding tests/test_<module_name>.py file. All external calls (subprocess, registry, filesystem) are mocked so tests run without network access or container tooling.

Tests run automatically in CI via .github/workflows/test.yml on every pull request and push to main.