From 025163d8e6070e5bc5e62dd1ac98d73773d5ccd8 Mon Sep 17 00:00:00 2001 From: Nathan Weinberg <31703736+nathan-weinberg@users.noreply.github.com> Date: Fri, 25 Jul 2025 11:57:01 -0400 Subject: [PATCH] feat: add auto-generated CI documentation pre-commit hook (#2890) # What does this PR do? Our CI is entirely undocumented, this commit adds a README.md file with a table of the current CI and what is does --------- Signed-off-by: Nathan Weinberg --- .github/workflows/README.md | 22 ++++++ .github/workflows/changelog.yml | 2 + .github/workflows/coverage-badge.yml | 2 + .github/workflows/install-script-ci.yml | 2 + .github/workflows/integration-auth-tests.yml | 2 + .../workflows/integration-sql-store-tests.yml | 2 + .github/workflows/integration-tests.yml | 2 + .../workflows/integration-vector-io-tests.yml | 2 + .github/workflows/pre-commit.yml | 2 + .github/workflows/providers-build.yml | 2 + .github/workflows/python-build-test.yml | 2 + .github/workflows/semantic-pr.yml | 2 + .github/workflows/stale_bot.yml | 2 + .../test-external-provider-module.yml | 2 + .github/workflows/test-external.yml | 2 + .github/workflows/unit-tests.yml | 2 + .github/workflows/update-readthedocs.yml | 2 + .pre-commit-config.yaml | 9 +++ docs/{readme.md => README.md} | 0 scripts/gen-ci-docs.py | 77 +++++++++++++++++++ 20 files changed, 140 insertions(+) create mode 100644 .github/workflows/README.md rename docs/{readme.md => README.md} (100%) create mode 100755 scripts/gen-ci-docs.py diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 000000000..3347b05f8 --- /dev/null +++ b/.github/workflows/README.md @@ -0,0 +1,22 @@ +# Llama Stack CI + +Llama Stack uses GitHub Actions for Continous Integration (CI). Below is a table detailing what CI the project includes and the purpose. + +| Name | File | Purpose | +| ---- | ---- | ------- | +| Update Changelog | [changelog.yml](changelog.yml) | Creates PR for updating the CHANGELOG.md | +| Coverage Badge | [coverage-badge.yml](coverage-badge.yml) | Creates PR for updating the code coverage badge | +| Installer CI | [install-script-ci.yml](install-script-ci.yml) | Test the installation script | +| Integration Auth Tests | [integration-auth-tests.yml](integration-auth-tests.yml) | Run the integration test suite with Kubernetes authentication | +| SqlStore Integration Tests | [integration-sql-store-tests.yml](integration-sql-store-tests.yml) | Run the integration test suite with SqlStore | +| Integration Tests | [integration-tests.yml](integration-tests.yml) | Run the integration test suite with Ollama | +| Vector IO Integration Tests | [integration-vector-io-tests.yml](integration-vector-io-tests.yml) | Run the integration test suite with various VectorIO providers | +| Pre-commit | [pre-commit.yml](pre-commit.yml) | Run pre-commit checks | +| Test Llama Stack Build | [providers-build.yml](providers-build.yml) | Test llama stack build | +| Python Package Build Test | [python-build-test.yml](python-build-test.yml) | Test building the llama-stack PyPI project | +| Check semantic PR titles | [semantic-pr.yml](semantic-pr.yml) | Ensure that PR titles follow the conventional commit spec | +| Close stale issues and PRs | [stale_bot.yml](stale_bot.yml) | Run the Stale Bot action | +| Test External Providers Installed via Module | [test-external-provider-module.yml](test-external-provider-module.yml) | Test External Provider installation via Python module | +| Test External API and Providers | [test-external.yml](test-external.yml) | Test the External API and Provider mechanisms | +| Unit Tests | [unit-tests.yml](unit-tests.yml) | Run the unit test suite | +| Update ReadTheDocs | [update-readthedocs.yml](update-readthedocs.yml) | Update the Llama Stack ReadTheDocs site | diff --git a/.github/workflows/changelog.yml b/.github/workflows/changelog.yml index c497348b0..e406d99ee 100644 --- a/.github/workflows/changelog.yml +++ b/.github/workflows/changelog.yml @@ -1,5 +1,7 @@ name: Update Changelog +run-name: Creates PR for updating the CHANGELOG.md + on: release: types: [published, unpublished, created, edited, deleted, released] diff --git a/.github/workflows/coverage-badge.yml b/.github/workflows/coverage-badge.yml index 54bde1749..75428539e 100644 --- a/.github/workflows/coverage-badge.yml +++ b/.github/workflows/coverage-badge.yml @@ -1,5 +1,7 @@ name: Coverage Badge +run-name: Creates PR for updating the code coverage badge + on: push: branches: [ main ] diff --git a/.github/workflows/install-script-ci.yml b/.github/workflows/install-script-ci.yml index c2b2113d7..5dc2b4412 100644 --- a/.github/workflows/install-script-ci.yml +++ b/.github/workflows/install-script-ci.yml @@ -1,5 +1,7 @@ name: Installer CI +run-name: Test the installation script + on: pull_request: paths: diff --git a/.github/workflows/integration-auth-tests.yml b/.github/workflows/integration-auth-tests.yml index cf10e005c..ef2066497 100644 --- a/.github/workflows/integration-auth-tests.yml +++ b/.github/workflows/integration-auth-tests.yml @@ -1,5 +1,7 @@ name: Integration Auth Tests +run-name: Run the integration test suite with Kubernetes authentication + on: push: branches: [ main ] diff --git a/.github/workflows/integration-sql-store-tests.yml b/.github/workflows/integration-sql-store-tests.yml index aeeecf395..4e5b64963 100644 --- a/.github/workflows/integration-sql-store-tests.yml +++ b/.github/workflows/integration-sql-store-tests.yml @@ -1,5 +1,7 @@ name: SqlStore Integration Tests +run-name: Run the integration test suite with SqlStore + on: push: branches: [ main ] diff --git a/.github/workflows/integration-tests.yml b/.github/workflows/integration-tests.yml index 808984368..c7b7fc55b 100644 --- a/.github/workflows/integration-tests.yml +++ b/.github/workflows/integration-tests.yml @@ -1,5 +1,7 @@ name: Integration Tests +run-name: Run the integration test suite with Ollama + on: push: branches: [ main ] diff --git a/.github/workflows/integration-vector-io-tests.yml b/.github/workflows/integration-vector-io-tests.yml index 525c17d46..9a02bbcf8 100644 --- a/.github/workflows/integration-vector-io-tests.yml +++ b/.github/workflows/integration-vector-io-tests.yml @@ -1,5 +1,7 @@ name: Vector IO Integration Tests +run-name: Run the integration test suite with various VectorIO providers + on: push: branches: [ main ] diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index 326abb37b..2c1c8febb 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -1,5 +1,7 @@ name: Pre-commit +run-name: Run pre-commit checks + on: pull_request: push: diff --git a/.github/workflows/providers-build.yml b/.github/workflows/providers-build.yml index 392fddda6..284076d50 100644 --- a/.github/workflows/providers-build.yml +++ b/.github/workflows/providers-build.yml @@ -1,5 +1,7 @@ name: Test Llama Stack Build +run-name: Test llama stack build + on: push: branches: diff --git a/.github/workflows/python-build-test.yml b/.github/workflows/python-build-test.yml index 33d1739a6..67dc49cce 100644 --- a/.github/workflows/python-build-test.yml +++ b/.github/workflows/python-build-test.yml @@ -1,5 +1,7 @@ name: Python Package Build Test +run-name: Test building the llama-stack PyPI project + on: push: branches: diff --git a/.github/workflows/semantic-pr.yml b/.github/workflows/semantic-pr.yml index 2dc1ed473..4df7324c4 100644 --- a/.github/workflows/semantic-pr.yml +++ b/.github/workflows/semantic-pr.yml @@ -1,5 +1,7 @@ name: Check semantic PR titles +run-name: Ensure that PR titles follow the conventional commit spec + on: pull_request_target: types: diff --git a/.github/workflows/stale_bot.yml b/.github/workflows/stale_bot.yml index 06318b5f7..087df72d7 100644 --- a/.github/workflows/stale_bot.yml +++ b/.github/workflows/stale_bot.yml @@ -1,5 +1,7 @@ name: Close stale issues and PRs +run-name: Run the Stale Bot action + on: schedule: - cron: '0 0 * * *' # every day at midnight diff --git a/.github/workflows/test-external-provider-module.yml b/.github/workflows/test-external-provider-module.yml index 30fddb981..284f9baa2 100644 --- a/.github/workflows/test-external-provider-module.yml +++ b/.github/workflows/test-external-provider-module.yml @@ -1,5 +1,7 @@ name: Test External Providers Installed via Module +run-name: Test External Provider installation via Python module + on: push: branches: [ main ] diff --git a/.github/workflows/test-external.yml b/.github/workflows/test-external.yml index d4b222e70..9dd72ad61 100644 --- a/.github/workflows/test-external.yml +++ b/.github/workflows/test-external.yml @@ -1,5 +1,7 @@ name: Test External API and Providers +run-name: Test the External API and Provider mechanisms + on: push: branches: [ main ] diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml index 41034b45f..f0c63f83d 100644 --- a/.github/workflows/unit-tests.yml +++ b/.github/workflows/unit-tests.yml @@ -1,5 +1,7 @@ name: Unit Tests +run-name: Run the unit test suite + on: push: branches: [ main ] diff --git a/.github/workflows/update-readthedocs.yml b/.github/workflows/update-readthedocs.yml index 981332a77..1dcfdeca5 100644 --- a/.github/workflows/update-readthedocs.yml +++ b/.github/workflows/update-readthedocs.yml @@ -1,5 +1,7 @@ name: Update ReadTheDocs +run-name: Update the Llama Stack ReadTheDocs site + on: workflow_dispatch: inputs: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index cf72ecd0e..a1acdbe84 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -145,6 +145,15 @@ repos: echo; exit 1; } || true + - id: generate-ci-docs + name: Generate CI documentation + additional_dependencies: + - uv==0.7.8 + entry: uv run ./scripts/gen-ci-docs.py + language: python + pass_filenames: false + require_serial: true + files: ^.github/workflows/.*$ ci: autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks diff --git a/docs/readme.md b/docs/README.md similarity index 100% rename from docs/readme.md rename to docs/README.md diff --git a/scripts/gen-ci-docs.py b/scripts/gen-ci-docs.py new file mode 100755 index 000000000..630cfe765 --- /dev/null +++ b/scripts/gen-ci-docs.py @@ -0,0 +1,77 @@ +#!/usr/bin/env python +# Copyright (c) Meta Platforms, Inc. and affiliates. +# All rights reserved. +# +# This source code is licensed under the terms described in the LICENSE file in +# the root directory of this source tree. + +from pathlib import Path + +import yaml + +REPO_ROOT = Path(__file__).parent.parent + + +def parse_workflow_file(file_path): + """Parse a workflow YAML file and extract name and run-name.""" + try: + with open(file_path, encoding="utf-8") as f: + content = yaml.safe_load(f) + + name = content["name"] + run_name = content["run-name"] + + return name, run_name + except Exception as e: + raise Exception(f"Error parsing {file_path}") from e + + +def generate_ci_docs(): + """Generate the CI documentation README.md file.""" + + # Define paths + workflows_dir = REPO_ROOT / ".github/workflows" + readme_path = workflows_dir / "README.md" + + # Header section to preserve + header = """# Llama Stack CI + +Llama Stack uses GitHub Actions for Continous Integration (CI). Below is a table detailing what CI the project includes and the purpose. + +| Name | File | Purpose | +| ---- | ---- | ------- | +""" + + # Get all .yml files in workflows directory + yml_files = [] + for file_path in workflows_dir.glob("*.yml"): + yml_files.append(file_path) + + # Sort files alphabetically for consistent output + yml_files.sort(key=lambda x: x.name) + + # Generate table rows + table_rows = [] + for file_path in yml_files: + name, run_name = parse_workflow_file(file_path) + filename = file_path.name + + # Create markdown link in the format [filename.yml](filename.yml) + file_link = f"[{filename}]({filename})" + + # Create table row + row = f"| {name} | {file_link} | {run_name} |" + table_rows.append(row) + + # Combine header and table rows + content = header + "\n".join(table_rows) + "\n" + + # Write to README.md + with open(readme_path, "w", encoding="utf-8") as f: + f.write(content) + + print(f"Generated {readme_path} with {len(table_rows)} workflow entries") + + +if __name__ == "__main__": + generate_ci_docs()