going back to initial version of qc.yml

akhilthomas17 · akhilthomas17 · commit d43301b4b0d2 · 2026-05-15T15:14:02.000+02:00
diff --git a/.github/workflows/qc.yml b/.github/workflows/qc.yml
@@ -1,8 +1,49 @@
-# Basic ODK workflow
+# ==============================================================================
+# WORKFLOW: Build Ontology (Quality Control)
+# ==============================================================================
+# Purpose: Builds ontology release assets and performs quality control checks
+#
+# This workflow:
+# 1. Refreshes imports to ensure consistency with upstream ontologies
+# 2. Generates release artifacts (OWL, JSON-LD, Turtle, etc.)
+# 3. Runs quality control checks (syntax, consistency, reasoning)
+# 4. Commits generated assets back to the repository
+# 5. Triggers the documentation workflow to continue the chain
+#
+# This is the core build workflow that transforms the edit file
+# (*-edit.owl) into production-ready ontology releases in multiple formats.
+#
+# Execution Chain Position:
+# setup-repo → [BUILD/QC] → docs
+# update-repo → [BUILD/QC] → docs
+# [BUILD/QC] → docs (on direct push to main)
+#
+# Read more about ODK builds:
+# https://github.com/INCATools/ontology-development-kit#building-the-ontology
+# ==============================================================================
 
-name: build
+name: Build Ontology
 
-# Controls when the action will run.
+# ==============================================================================
+# WORKFLOW TRIGGERS
+# ==============================================================================
+# This workflow can be triggered in four ways:
+# 1. Via repository_dispatch from setup-repo or update-repo workflow
+# 2. Automatically on pushes to main that modify ontology source files
+# 3. Automatically on pull requests that modify ontology source files
+# 4. Manually via workflow_dispatch for forced builds
+#
+# Path filters ensure the workflow only runs when ontology files change,
+# preventing unnecessary builds on unrelated commits (README, docs, etc.).
+#
+# IMPORTANT: The push trigger here only monitors ontology source/edit files.
+# The refresh-imports workflow independently monitors import-related files
+# and is used only for standalone import refreshes (workflow_dispatch /
+# repository_dispatch). This prevents double-triggering on import changes.
+#
+# IMPORTANT: Push triggers skip commits made by github-actions[bot] to prevent
+# duplicate runs when the workflow chain is triggered via repository_dispatch.
+# ==============================================================================
 on:
   # ============================================================================
   # TRIGGER 1: Repository Dispatch (from setup-repo or update-repo workflow)
@@ -62,34 +103,200 @@ on:
       - 'src/ontology/Makefile'
       - 'src/ontology/*-Makefile'
 
-  # Allows you to run this workflow manually from the Actions tab
+  # ============================================================================
+  # TRIGGER 4: Manual Trigger (for forced builds or debugging)
+  # ============================================================================
+  # Allows manual execution via GitHub UI or API.
+  # Useful for:
+  # - Forcing rebuild after external changes (e.g. upstream ontology update)
+  # - Troubleshooting build issues without touching source files
+  # - Testing the complete pipeline end-to-end
+  # ============================================================================
   workflow_dispatch:
 
-# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+# ==============================================================================
+# ENVIRONMENT VARIABLES
+# ==============================================================================
+# Global variables available to all jobs in this workflow
+# ==============================================================================
+env:
+  # Default branch for git operations (used in some ODK make targets)
+  DEFAULT_BRANCH: main
+
+# ==============================================================================
+# JOBS
+# ==============================================================================
 jobs:
-  # This workflow contains a single job called "ontology_qc"
+  # ============================================================================
+  # JOB: ontology_qc
+  # ============================================================================
+  # Main job that performs the complete build and QC process.
+  #
+  # Process Flow:
+  # 1. Checkout repository with full history
+  # 2. Build ontology (runs make refresh-imports + all_assets inside ODK container)
+  # 3. Commit generated release files back to the repository
+  # 4. Trigger documentation generation workflow (docs.yml)
+  #
+  # Container: obolibrary/odkfull:v1.6
+  # - Includes ROBOT, OWLTools, make, Java, Python, reasoning tools
+  # - Version pinned for reproducibility
+  #
+  # Permissions: contents: write (required for committing release artifacts)
+  # ============================================================================
   ontology_qc:
-    # The type of runner that the job will run on
     runs-on: ubuntu-latest
+
+    # Grant write permissions for committing generated release assets back to repo
+    permissions:
+      contents: write
+
+    # Use ODK container for a consistent, reproducible build environment.
+    # odkfull includes: ROBOT (OWL reasoner + transformer), make, Java, Python,
+    # yq (YAML processor), and all ODK tooling required for ontology builds.
     container: obolibrary/odkfull:v1.6
 
-    # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v4
-      
-      - name: ODK update
-        run: cd src/ontology && odk.py update
+      # ========================================================================
+      # STEP 1: Checkout Repository
+      # ========================================================================
+      # Fetch complete repository with full git history.
+      #
+      # Why fetch-depth: 0 (full history)?
+      # - ODK make targets may inspect git history for versioning
+      # - Ensures accurate version numbers in release artifacts
+      # - Allows git operations (log, describe) within build scripts
+      # ========================================================================
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full git history required for ODK builds
 
-      - name: Build ontology
+      # ========================================================================
+      # STEP 2: Build Ontology (Refresh Imports + Generate All Artifacts)
+      # ========================================================================
+      # Runs two ODK make targets inside the odkfull container:
+      #
+      # Target 1: refresh-imports
+      #   - Downloads and extracts terms from upstream ontologies
+      #   - Updates all import module OWL files (imports/*_import.owl)
+      #   - Uses SLME (Syntactic Locality Module Extraction) for minimal imports
+      #   - Reads term lists from imports/*_terms.txt
+      #
+      # Target 2: all_assets
+      #   Generates all release artifacts:
+      #   - {id}-full.owl     : Complete ontology (all imports merged)
+      #   - {id}-base.owl     : Core ontology without transitive imports
+      #   - {id}.owl          : Main release file
+      #   - {id}.json         : JSON-LD serialization
+      #   - {id}.ttl          : Turtle serialization
+      #   - {id}-simple.owl   : Simplified version (if configured)
+      #   - {id}-non-classified.owl : Pre-reasoning version (if configured)
+      #   - Component OWL files, QC reports, statistics
+      #
+      # Memory configuration (ROBOT_ENV):
+      #   ROBOT_ENV is consumed by the ODK Makefile as a prefix to the ROBOT
+      #   command: `$(ROBOT_ENV) robot ...`. Setting ROBOT_JAVA_ARGS=-Xmx6G
+      #   allocates 6GB Java heap to ROBOT, which is required for reasoning
+      #   over large ontologies. Increase to -Xmx8G if you see OutOfMemory errors.
+      # ========================================================================
+      - name: Build ontology (refresh imports + generate all release assets)
         env:
-          CRYO_TOKEN: ${{ secrets.CRYO_TOKEN }}
-          DEFAULT_BRANCH: main
-        run: cd src/ontology && make refresh-imports all_assets ROBOT_ENV='ROBOT_JAVA_ARGS=-Xmx6G' -vvv
-      - name: Commit files # commit the src folder
+          # Configure ROBOT Java heap: 6GB is sufficient for most ontologies.
+          # Increase to -Xmx8G or -Xmx12G if OOM errors occur during reasoning.
+          ROBOT_ENV: 'ROBOT_JAVA_ARGS=-Xmx6G'
+        run: |
+          # Navigate to the ODK ontology source directory
+          cd src/ontology
+
+          echo "=== Starting ODK build ==="
+          echo "Step 2a: Refreshing ontology imports..."
+          echo "Step 2b: Generating all release assets..."
+
+          # Run both ODK targets:
+          # - refresh-imports : Mirrors external ontologies and extracts SLME modules
+          # - all_assets      : Generates all release serializations and runs QC
+          make refresh-imports all_assets
+
+          echo "=== Build complete ==="
+
+      # ========================================================================
+      # STEP 3: Commit Ontology Release Assets
+      # ========================================================================
+      # Commits the generated release files back to the repository so they are
+      # versioned alongside the source and available for the docs workflow.
+      #
+      # Conditions:
+      # - SKIPPED for pull requests: PR contributors should review changes manually
+      #   before merge; artifacts are not committed on PR runs.
+      # - Only commits if there are actual changes (EndBug/add-and-commit@v9
+      #   automatically skips empty commits).
+      #
+      # Files committed:
+      # - src/ontology/*.owl   : All OWL serializations (full, base, simple, etc.)
+      # - src/ontology/*.json  : JSON-LD serializations
+      # - src/ontology/*.ttl   : Turtle serializations
+      # - src/ontology/imports/*.owl : Updated import modules
+      #
+      # Why --force?
+      # - ODK generates these files but they may be listed in .gitignore
+      # - --force overrides .gitignore so release artifacts are versioned
+      # - This is intentional: release assets should be tracked for distribution
+      #
+      # Commit identity:
+      # - Author set to github-actions[bot] to distinguish automated commits
+      #   from human developer commits in git log
+      # ========================================================================
+      - name: Commit ontology release assets
+        # Only commit for push and dispatch events — skip for pull requests
+        if: github.event_name != 'pull_request'
         uses: EndBug/add-and-commit@v9
         with:
-          message: "updated ontology"
-          cwd: "." # Crucial: Look at the whole repo
-          add: "*.owl src/**/* --force" # Capture root owls and src folder
+          # Descriptive message — visible in git log, easy to filter
+          message: "Building the ontology from the edits"
+
+          # Repository root as working directory
+          cwd: "."
+
+          # Add all generated files; --force bypasses .gitignore for artifacts
+          add: "src/ontology/*.owl src/ontology/*.json src/ontology/*.ttl src/ontology/imports/*.owl --force"
+
+          # Commit as the GitHub Actions bot (standard identity for CI commits)
           default_author: github_actions
+
+          # Push directly to the current branch
+          push: true
+
+      # ========================================================================
+      # STEP 4: Trigger Documentation Workflow
+      # ========================================================================
+      # After the ontology is successfully built and committed, dispatch a
+      # repository event to start the Widoco documentation generation workflow.
+      #
+      # Workflow chain:
+      #   setup-repo ─→ [this: BUILD/QC] ─→ docs
+      #   update-repo ─→ [this: BUILD/QC] ─→ docs
+      #   push to main ─→ [this: BUILD/QC] ─→ docs
+      #
+      # Why repository_dispatch and not a direct workflow call?
+      # - Maintains clean separation between workflow stages
+      # - Avoids nested workflow complexity (GitHub has limits on chained calls)
+      # - Ensures docs always build from the committed artifact, not mid-run state
+      # - Prevents race conditions between build commit and docs generation
+      #
+      # The 'trigger-docs' event is listened for by docs.yml.
+      #
+      # Condition: Only dispatch for non-PR events.
+      # - PRs do not deploy to Pages; docs are rebuilt after PR merge to main.
+      # ========================================================================
+      - name: Trigger Documentation Workflow
+        # Skip for pull requests — docs will be regenerated after PR merge
+        if: github.event_name != 'pull_request'
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          # GITHUB_TOKEN is automatically available with the 'contents: write'
+          # permission set on this job. No PAT required.
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+          # Event type that docs.yml listens for via repository_dispatch trigger
+          event-type: trigger-docs
