main.yaml

on:
  push:
  pull_request:
  merge_group:

name: CI
jobs:

  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version:
        - '3.9'
        - '3.10'
        - '3.11'
        - '3.12'
        - '3.13'
        - 'pypy-3.9'
        - 'pypy-3.10'
        allow-failure:
        - false
        include:
        - python-version: '3.14-dev'
          allow-failure: true
    continue-on-error: ${{ matrix.allow-failure }}
    name: 'test (${{ matrix.python-version }})'
    steps:
    - name: Check out source code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: Set up PDM
      uses: pdm-project/setup-pdm@v4
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys FA8E1301F4D3932C
        sudo add-apt-repository 'deb http://ppa.launchpad.net/sri-csl/formal-methods/ubuntu bionic main'
        sudo apt-get update
        sudo apt-get install yices2
        pip install codecov build
        pdm install --dev
    - name: Cache YoWASP build products
      uses: actions/cache@v4
      with:
        path: ~/.cache/YoWASP
        key: YoWASP-${{ runner.os }}-${{ hashFiles('./.venv/**/*.wasm') }}
        restore-keys: |
          YoWASP-${{ runner.os }}-
    - name: Run tests
      run: |
        pdm run test
    - name: Submit code coverage
      run: |
        codecov

  smoketest: # If we plug this into downstream projects, does magic smoke escape?
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        project:
          - amaranth-lang/amaranth-boards
          - amaranth-lang/amaranth-stdio
          - amaranth-lang/amaranth-soc
    name: 'smoke (${{ matrix.project }})'
    steps:
    - name: Check out Amaranth source code
      uses: actions/checkout@v4
      with:
        path: amaranth
        fetch-depth: 0
    - name: Check out source code
      uses: actions/checkout@v4
      with:
        repository: ${{ matrix.project }}
        path: project
        fetch-depth: 0
    - name: Set up PDM
      uses: pdm-project/setup-pdm@v4
    - name: Install dependencies
      working-directory: project
      run: |
        pdm install --dev
    - name: Use Amaranth HEAD revision
      working-directory: project
      run: |
        pdm add ../amaranth
    - name: Cache YoWASP build products
      uses: actions/cache@v4
      with:
        path: ~/.cache/YoWASP
        key: YoWASP-${{ runner.os }}-${{ hashFiles('./.venv/**/*.wasm') }}
        restore-keys: |
          YoWASP-${{ runner.os }}-
    - name: Run tests
      working-directory: project
      run: |
        pdm run test

  document:
    runs-on: ubuntu-latest
    steps:
      - name: Check out source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Fetch tags from upstream repository
        run: |
          git fetch --tags https://github.com/amaranth-lang/amaranth.git
      - name: Set up PDM
        uses: pdm-project/setup-pdm@v4
        with:
          python-version: '3.12'
      - name: Install dependencies
        run: |
          pdm install --dev
      - name: Build documentation
        run: |
          pdm run document
      - name: Upload documentation archive
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: docs/_build
      - name: Extract schemas
        run: |
          pdm run extract-schemas
      - name: Upload schema archive
        uses: actions/upload-artifact@v4
        with:
          name: schema
          path: schema

  check-links:
    runs-on: ubuntu-latest
    steps:
      - name: Check out source code
        uses: actions/checkout@v4
        with:
            fetch-depth: 0
      - name: Set up PDM
        uses: pdm-project/setup-pdm@v4
        with:
          python-version: '3.12'
      - name: Install dependencies
        run: |
          pdm install --dev
      - name: Check links in documentation
        run: |
          pdm run document-linkcheck

  required: # group all required workflows into one to avoid reconfiguring this in Actions settings
    needs:
      - test
      - document
    if: ${{ always() && !contains(needs.*.result, 'cancelled') }}
    runs-on: ubuntu-latest
    steps:
      - run: ${{ contains(needs.*.result, 'failure') && 'false' || 'true' }}

  publish-docs:
    needs: document
    if: ${{ github.repository == 'amaranth-lang/amaranth' }}
    runs-on: ubuntu-latest
    steps:
      - name: Check out source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Download documentation archive
        uses: actions/download-artifact@v4
        with:
          name: docs
          path: docs/
      - name: Publish development documentation
        if: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
        uses: JamesIves/github-pages-deploy-action@releases/v4
        with:
          repository-name: amaranth-lang/amaranth-lang.github.io
          ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
          branch: main
          folder: docs/
          target-folder: docs/amaranth/latest/
      - name: Publish release documentation
        if: ${{ github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') && !contains(github.event.ref, 'dev') }}
        uses: JamesIves/github-pages-deploy-action@releases/v4
        with:
          repository-name: amaranth-lang/amaranth-lang.github.io
          ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
          branch: main
          folder: docs/
          target-folder: docs/amaranth/${{ github.ref_name }}/

  publish-docs-dev:
    needs: document
    if: ${{ github.repository != 'amaranth-lang/amaranth' }}
    runs-on: ubuntu-latest
    steps:
      - name: Check out source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Download documentation archive
        uses: actions/download-artifact@v4
        with:
          name: docs
          path: pages/docs/${{ github.ref_name }}/
      - name: Disable Jekyll
        run: |
          touch pages/.nojekyll
      - name: Publish documentation for a branch
        uses: JamesIves/github-pages-deploy-action@releases/v4
        with:
          folder: pages/
          clean: false

  publish-schemas:
    needs: [required, publish-docs] # avoid race condition with publish-docs
    if: ${{ github.repository == 'amaranth-lang/amaranth' }}
    runs-on: ubuntu-latest
    steps:
      - name: Check out source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Download schema archive
        uses: actions/download-artifact@v4
        with:
          name: schema
          path: schema/
      - name: Publish schemas
        if: ${{ github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
        uses: JamesIves/github-pages-deploy-action@releases/v4
        with:
          repository-name: amaranth-lang/amaranth-lang.github.io
          ssh-key: ${{ secrets.PAGES_DEPLOY_KEY }}
          branch: main
          folder: schema/
          target-folder: schema/amaranth/

  publish-package:
    needs: required
    runs-on: ubuntu-latest
    environment: publish
    permissions:
      id-token: write
    steps:
    - name: Check out source code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0
    - name: Build package
      run: |
        pip install build
        python -m build
    - name: Upload package artifact
      uses: actions/upload-artifact@v4
      with:
        name: package
        path: dist/
    - name: Verify package metadata
      run: |
        pip install twine
        twine check dist/*
    - name: Publish package to Test PyPI
      if: ${{ github.repository == 'amaranth-lang/amaranth' && github.event_name == 'push' && github.event.ref == 'refs/heads/main' }}
      uses: pypa/gh-action-pypi-publish@release/v1
      with:
        repository-url: https://test.pypi.org/legacy/
    - name: Publish package to PyPI
      if: ${{ github.repository == 'amaranth-lang/amaranth' && github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') && !contains(github.event.ref, 'dev') }}
      uses: pypa/gh-action-pypi-publish@release/v1

  publish-release:
    needs: publish-package
    if: ${{ github.repository == 'amaranth-lang/amaranth' && github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v') && !contains(github.event.ref, 'dev') }}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - name: Determine release metadata
      id: metadata
      env:
        REF_NAME: ${{ github.ref_name }}
      run: |
        echo name=${REF_NAME/v/} >>$GITHUB_OUTPUT
    - name: Create release
      uses: comnoco/create-release-action@v2
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        tag_name: ${{ github.ref_name }}
        release_name: ${{ steps.metadata.outputs.name }}