amaranth/.github/workflows/main.yaml

on:
  push:
  pull_request:
  merge_group:

name: CI
jobs:

  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version:
        - '3.8'
        - '3.9'
        - '3.10'
        - '3.11'
        - '3.12'
        - 'pypy-3.8'
        - 'pypy-3.9'
        - 'pypy-3.10'
        allow-failure:
        - false
        include:
        - python-version: '3.13-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        

  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

  check-links:
    runs-on: ubuntu-latest
    steps:
      - name: Check out source code
        uses: actions/checkout@v4
      - 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') }}
        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-code:
    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: code
        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/') }}
      uses: pypa/gh-action-pypi-publish@release/v1