_publish-gem.yml

# =========================================================================
#   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

      # Capture the short SHA for the GIT_COMMIT_SHA file embedded in the gem
      - name: Capture Git Commit Short SHA
        shell: bash
        run: echo "sha_short=$(git rev-parse --short HEAD)" >> "$GITHUB_ENV"

      # Create GIT_COMMIT_SHA file in the repo root — packaged into the gem for runtime version reporting
      - name: Create GIT_COMMIT_SHA File
        shell: bash
        run: echo "${{ env.sha_short }}" > "$GITHUB_WORKSPACE/GIT_COMMIT_SHA"

      # 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 }}