Feature: Partials

.github/workflows/_generate-docs.yml

@@ -0,0 +1,75 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# -----------------------------------------------------------------------
+# Internal reusable workflow — not intended to be triggered directly.
+# Called by ci.yml, prerelease.yml, and release.yml.
+#
+# Purpose:
+#   Build the local HTML documentation bundle (MkDocs) for inclusion in
+#   the Ceedling gem and upload it as the artifact 'gem-docs-site-local'.
+#   Subsequent jobs in the calling workflow download this artifact to
+#   make the docs bundle available for testing and gem packaging.
+# -----------------------------------------------------------------------
+
+---
+name: "Generate Local Docs Bundle"
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  generate-docs:
+    name: "Generate Local Docs Bundle for Gem Inclusion"
+    runs-on: ubuntu-latest
+
+    steps:
+      # Use a cache for our tools to speed up builds
+      # No matrix here; Ruby version is hardcoded to match the cache key format used by test jobs
+      - uses: actions/cache@v4
+        with:
+          path: vendor/bundle
+          key: bundle-use-ruby-${{ runner.os }}-3.3-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            bundle-use-ruby-${{ runner.os }}-3.3-
+
+      - name: Checkout Latest Repo
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set Up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+
+      # This is overkill, but it's the sanest way to ensure all Rakefile dependencies are available when we run docs:build:local task
+      - name: Install Gem Dependencies
+        run: |
+          bundle install
+
+      # --break-system-packages is required on Ubuntu 24.04+ (PEP 668 prevents pip from
+      # installing to the system Python environment without explicit opt-in)
+      - name: Install MkDocs and mkdocs-material
+        run: |
+          pip install --break-system-packages mkdocs mkdocs-material
+
+      # Builds local HTML bundle for gem inclusion; invokes MkDocs via the project's
+      # venv_sh wrapper in the Rakefile (skips venv activation when no .docsenv is present)
+      - name: Build HTML Documentation Bundle
+        run: |
+          rake docs:build:local --trace
+
+      - name: Upload HTML Documentation Bundle
+        uses: actions/upload-artifact@v4
+        with:
+          name: gem-docs-site-local
+          path: site-local/
+          if-no-files-found: error

.github/workflows/_publish-gem.yml

@@ -0,0 +1,159 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+# -----------------------------------------------------------------------
+# Internal reusable workflow — not intended to be triggered directly.
+# Called by prerelease.yml (with prerelease: true) and release.yml
+# (with prerelease: false).
+#
+# Purpose:
+#   Stamp the gem version from the calling workflow's Git tag, build the
+#   Ceedling gem, and publish a GitHub release or pre-release using
+#   softprops/action-gh-release@v2.
+#
+# Version stamping:
+#   lib/version.rb carries a .dev suffix between releases (e.g. 1.1.1.dev).
+#   This job derives the actual release version from the Git tag and stamps
+#   it into lib/version.rb before building — the file is never manually
+#   edited to match a release tag.
+#
+#   Tag-to-gem-version conversion:
+#     v1.1.0-pre.1  →  1.1.0.pre.1  (hyphen becomes dot: RubyGems pre-release notation)
+#     v1.1.0        →  1.1.0         (no suffix; substitution is a no-op)
+#
+# RubyGems.org publishing:
+#   The "Push to RubyGems.org" step below is stubbed and commented out.
+#   To enable automated publishing: uncomment the step and add a
+#   RUBYGEMS_API_KEY secret to the repository settings.
+# -----------------------------------------------------------------------
+
+---
+name: "Build and Publish Gem"
+
+on:
+  workflow_call:
+    inputs:
+      prerelease:
+        type: boolean
+        required: true
+        description: 'true = GitHub pre-release, false = full release'
+
+# contents: write is required to create and upload GitHub releases
+permissions:
+  contents: write
+
+jobs:
+  build-and-publish:
+    name: "Build and Publish Ceedling Gem"
+    runs-on: ubuntu-latest
+
+    steps:
+      # Use a cache for our tools to speed up builds
+      # No matrix here; Ruby version is hardcoded to match the cache key format used by test jobs
+      - uses: actions/cache@v4
+        with:
+          path: vendor/bundle
+          key: bundle-use-ruby-${{ runner.os }}-3.3-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            bundle-use-ruby-${{ runner.os }}-3.3-
+
+      - name: Checkout Latest Repo
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set Up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+
+      - name: Install Gem Dependencies
+        run: |
+          bundle install
+
+      # Derive the gem version from the Git tag and stamp it into lib/version.rb.
+      # The in-tree version.rb carries a .dev suffix between releases; the release
+      # version is computed here from the tag and is never manually set.
+      - name: Stamp Gem Version from Git Tag
+        shell: bash
+        run: .github/workflows/stamp_gem_version.sh "${GITHUB_REF_NAME}" lib/version.rb
+
+      # Extract the changelog section matching this release version for use as the
+      # release body. The script exits 0 (found) or 1 (not found / file missing).
+      # Shell vars don't persist across steps; version is re-derived from the tag.
+      - name: Extract Changelog Section for Release Notes
+        id: changelog
+        shell: bash
+        run: |
+          # Strip the leading 'v' then take only the MAJOR.MINOR.PATCH core,
+          # discarding any pre-release suffix (e.g. v1.2.3-pre.1 → 1.2.3).
+          # Changelog entries are keyed on the semver core, not the full tag.
+          SEMVER="${GITHUB_REF_NAME#v}"
+          SEMVER="${SEMVER%%-*}"
+          BODY_FILE="${RUNNER_TEMP}/release_body.md"  # $RUNNER_TEMP: Actions-provided temp dir
+
+          echo "found=false" >> "$GITHUB_OUTPUT"
+
+          if .github/workflows/extract_changelog.sh "${SEMVER}" "docs/Changelog.md" "${BODY_FILE}"; then
+            # Write the extracted markdown content as a multi-line step output.
+            # A unique timestamp-based delimiter guards against any text in the changelog
+            # accidentally matching the EOF marker and closing the heredoc early.
+            EOF_MARKER="RELEASE_BODY_EOF_$(date +%s)"
+            echo "body<<${EOF_MARKER}" >> "$GITHUB_OUTPUT"
+            cat "${BODY_FILE}"         >> "$GITHUB_OUTPUT"
+            echo "${EOF_MARKER}"       >> "$GITHUB_OUTPUT"
+            echo "found=true"          >> "$GITHUB_OUTPUT"
+          fi
+
+      # Download HTML docs bundle built by _generate-docs.yml
+      # Artifacts are shared within the same workflow run by run_id
+      - name: Download HTML Documentation Bundle
+        uses: actions/download-artifact@v4
+        with:
+          name: gem-docs-site-local
+          path: site-local/
+
+      - name: Build Gem
+        run: |
+          gem build ceedling.gemspec
+
+      # softprops/action-gh-release@v2 replaces the archived actions/create-release@v1
+      # and actions/upload-release-asset@v1.
+      # Two conditional steps are used because the action cannot switch between
+      # body and generate_release_notes within a single step via expressions.
+
+      # Use the extracted changelog section as the release body when the section was found
+      - name: Log Release Notes Source (changelog body)
+        if: steps.changelog.outputs.found == 'true'
+        run: echo "Publishing release with Changelog.md section as release notes body."
+
+      - name: Publish GitHub Release (changelog body)
+        if: steps.changelog.outputs.found == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          prerelease: ${{ inputs.prerelease }}
+          files: ceedling-*.gem
+          body: ${{ steps.changelog.outputs.body }}
+
+      # Fall back to GitHub's auto-generated release notes (from last commit)
+      # when no changelog section exists for this version
+      - name: Log Release Notes Source (auto-generated)
+        if: steps.changelog.outputs.found != 'true'
+        run: echo "No Changelog.md section found for this version; publishing release with GitHub auto-generated release notes."
+
+      - name: Publish GitHub Release (auto-generated notes)
+        if: steps.changelog.outputs.found != 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          prerelease: ${{ inputs.prerelease }}
+          files: ceedling-*.gem
+
+      # Uncomment and add RUBYGEMS_API_KEY secret to automate RubyGems.org publishing
+      # - name: Push to RubyGems.org
+      #   run: gem push ceedling-*.gem
+      #   env:
+      #     GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}