chore: Merge branch 'main' into iss-162

.github/workflows/build.yml

@@ -22,6 +22,7 @@ env:
 jobs:
   build:
     runs-on: ubuntu-latest
+    timeout-minutes: 2
     strategy:
       matrix:
         python-version: ["3.9"]

.github/workflows/docs.yml

@@ -1,27 +1,89 @@
-name: mkdocs_build
+name: docs
 on:
   workflow_dispatch:
+  release:
+    types:
+      - published
   push:
     branches:
       - main
     paths:
       - "docs/**"
+      - "**.md"
+      - .github/workflows/docs.yml
+      - mkdocs.yml
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "**.md"
+      - .github/workflows/docs.yml
+      - mkdocs.yml
 
 env:
   actor: "41898282+github-actions[bot]"
+  GH_TOKEN: ${{ github.token }}
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
         with:
-          python-version: 3.9
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+          cache: pip
+      - run: pip install --upgrade pip -r docs/requirements.txt
       - name: git config
         run: |
           git config --local user.email "${actor}@users.noreply.github.com"
           git config --local user.name "$actor"
-      - run: pip install --upgrade pip
-      - run: pip install -r docs/requirements.txt
-      - run: mkdocs gh-deploy --force
+          gh release list > releases.tsv
+      - name: get version tag & alias
+        shell: python {0}
+        run: |
+          import os
+          import re
+          import warnings
+
+          release_tag = ''
+          with open('releases.tsv', 'r') as infile:
+            for line in infile:
+              release_name, latest, tag, timestamp = line.strip().split('\t')
+              if latest == "Latest":
+                release_tag = tag.strip('v')
+                break
+          if not release_tag:
+            warnings.warn("No latest release found")
+
+          with open('VERSION', 'r') as infile:
+            current_version = infile.read().strip()
+
+          if current_version == release_tag:
+            docs_alias = 'latest'
+            docs_version = release_tag
+          else:
+            semver_pattern = '(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?'
+            release_semver = re.match(semver_pattern, release_tag)
+            current_semver = re.match(semver_pattern, current_version)
+
+            groups = ['major', 'minor', 'patch']
+            if current_semver.group('prerelease') and any([current_semver.group(grp) >= release_semver.group(grp) for grp in groups]):
+              docs_alias = ''
+              docs_version = 'dev'
+            else:
+              raise ValueError(f"current version {current_version} is not greater than latest release {release_tag}")
+
+          with open(os.getenv("GITHUB_ENV"), 'a') as out_env:
+            out_env.write(f"VERSION={docs_version}\n")
+            out_env.write(f"ALIAS={docs_alias}\n")
+
+      - name: deploy docs
+        run: |
+          mike deploy ${{ env.VERSION }} ${{ env.ALIAS }} \
+            --push \
+            --update-aliases \
+            --branch gh-pages

.github/workflows/draft-release.yml

@@ -0,0 +1,150 @@
+name: draft-release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version_tag:
+        description: |
+          Semantic version tag for next release.
+          If not provided, it will be determined based on conventional commit history.
+          Example: v2.5.11
+        required: false
+        type: string
+        default: ""
+
+env:
+  GH_TOKEN: ${{ github.token }}
+  BRANCH: release-draft
+
+jobs:
+  draft-release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # required to include tags
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+          cache: "pip"
+      - run: pip install cffconvert>=2.0.0 pyyaml
+
+      - name: Get Date
+        run: |
+          echo "DATE=$(date +"%Y-%m-%d")" >> "$GITHUB_ENV"
+
+      - name: Get current and next versions
+        id: semver
+        uses: ietf-tools/semver-action@v1
+        with:
+          token: ${{ github.token }}
+          branch: ${{ github.ref_name }}
+
+      - name: Set version variables
+        shell: python {0}
+        run: |
+          import os
+          import re
+          import warnings
+
+          convco_version = "${{ steps.semver.outputs.next }}"
+          if "${{ github.event_name }}" == 'workflow_dispatch' and "${{ github.event.inputs.version_tag }}":
+            next_version = "${{ github.event.inputs.version_tag }}"
+            if next_version != convco_version:
+              warnings.warn(f"Manual version ({next_version}) not equal to version determined by conventional commit history ({convco_version})")
+          else:
+            next_version = convco_version
+
+          with open(os.getenv("GITHUB_ENV"), 'a') as out_env:
+            out_env.write(f"NEXT_VERSION={next_version}\n")
+            out_env.write(f"NEXT_STRICT={next_version.strip('v')}\n")
+          current_version = "${{ steps.semver.outputs.current }}"
+
+          # assert semantic version pattern
+          semver_pattern = 'v(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?'
+          next_semver = re.match(semver_pattern, next_version)
+          if not next_semver:
+            extra_msg = ''
+            if not next_version.startswith('v'):
+              extra_msg = "The tag does not start with 'v'."
+            raise ValueError(f"Tag {next_version} does not match semantic versioning guidelines. {extra_msg}\nView the guidelines here: https://semver.org/")
+
+          # assert next version is only 1 greater than current
+          current_semver = re.match(semver_pattern, current_version)
+          groups = ['major', 'minor', 'patch']
+          greater = sum([next_semver.group(grp) > current_semver.group(grp) for grp in groups])
+          if not (greater == 1):
+            raise ValueError(f"Next version must only increment one number at a time. Current version: {current_version}. Proposed next version: {next_version}")
+
+      - name: Get release notes, update changelog & version file
+        shell: python {0}
+        run: |
+          import os
+          latest_version = "${{ steps.semver.outputs.current }}".strip('v')
+          next_version = "${{ env.NEXT_STRICT }}"
+
+          changelog_lines = list()
+          next_release_lines = list()
+          for_next = True
+          with open("CHANGELOG.md", "r") as infile:
+            for line in infile:
+              if line.startswith('#') and 'development version' in line:
+                line = line.replace('development version', next_version)
+              elif latest_version in line:
+                for_next = False
+
+              changelog_lines.append(line)
+              if for_next and next_version not in line:
+                next_release_lines.append(line)
+
+          with open(".github/latest-release.md", "w") as outfile:
+            outfile.writelines(next_release_lines)
+          with open('CHANGELOG.md', 'w') as outfile:
+            outfile.writelines(changelog_lines)
+          with open("VERSION", "w") as outfile:
+            outfile.write(f"{next_version}\n")
+
+      - name: Update citation
+        shell: python {0}
+        run: |
+          from cffconvert.cli.create_citation import create_citation
+          from cffconvert.cli.validate_or_write_output import validate_or_write_output
+          import yaml
+
+          citation = create_citation('CITATION.cff', None)
+          citation._implementation.cffobj['version'] = "${{ env.NEXT_VERSION }}"
+          citation._implementation.cffobj['date-released'] = "${{ env.DATE }}"
+          with open('CITATION.cff', 'w') as outfile:
+            outfile.write(yaml.dump(citation._implementation.cffobj, sort_keys=False, indent=2))
+
+      - uses: pre-commit/[email protected]
+        with:
+          extra_args: --files CITATION.cff CHANGELOG.md VERSION
+        continue-on-error: true
+
+      - name: Commit & push to branch
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          git push origin --delete ${{ env.BRANCH }} || echo "No ${{ env.BRANCH }} branch to delete"
+          git switch -c ${{ env.BRANCH }} || git switch ${{ env.BRANCH }}
+          git merge --ff-only ${{ github.ref_name }}
+
+          git add CITATION.cff CHANGELOG.md VERSION
+          git commit -m 'chore: prepare release ${{ env.NEXT_VERSION }}'
+          git push --set-upstream origin ${{ env.BRANCH }}
+
+          echo "COMMIT_HASH=$(git rev-parse HEAD)" >> "$GITHUB_ENV"
+
+      - name: Tag & draft release
+        run: |
+          gh release create ${{ env.NEXT_VERSION }} \
+            --draft \
+            --notes-file .github/latest-release.md \
+            --target ${{ env.COMMIT_HASH }} \
+            --title "${{ github.event.repository.name }} ${{ env.NEXT_STRICT }}"
+
+      - name: Next steps
+        run: |
+          echo "Next steps: Take a look at the changes in the ${{ env.BRANCH }} branch and the release notes on the web. If everything is correct, publish the release. Otherwise, delete the release draft and cut the release manually."

.github/workflows/post-release.yml

@@ -0,0 +1,56 @@
+name: post-release
+
+on:
+  release:
+    types:
+      - published
+
+env:
+  GH_TOKEN: ${{ github.token }}
+  BRANCH: release/${{ github.ref_name }}
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Configure git
+        run: |
+          git config --local user.name "github-actions[bot]"
+          git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git push origin --delete ${{ env.BRANCH }} || echo "No ${{ env.BRANCH }} branch to delete"
+          git switch -c ${{ env.BRANCH }}
+      - name: Bump changelog & version
+        shell: python {0}
+        run: |
+          with open("CHANGELOG.md", "r") as infile:
+            lines = infile.readlines()
+          lines.insert(0, "## ${{ github.event.repository.name }} development version\n\n")
+          with open("CHANGELOG.md", "w") as outfile:
+            outfile.writelines(lines)
+
+          with open('VERSION', 'r') as infile:
+            version = infile.read().strip()
+          with open('VERSION', 'w') as outfile:
+            outfile.write(f"{version}-dev\n")
+
+      - uses: pre-commit/[email protected]
+        with:
+          extra_args: --files CITATION.cff CHANGELOG.md VERSION
+        continue-on-error: true
+
+      - name: Open pull request
+        run: |
+          git add CHANGELOG.md VERSION
+          git commit -m "chore: bump changelog & version after release of ${{ github.ref_name }}"
+          git push --set-upstream origin ${{ env.BRANCH }}
+
+          gh pr create \
+            --fill-first \
+            --reviewer ${{ github.triggering_actor }}
+
+      - name: Clean up release-draft branch
+        run: |
+          git push origin --delete release-draft || echo "No release-draft branch to delete"

.pre-commit-config.yaml

@@ -3,7 +3,8 @@ default_stages: [pre-commit]
 exclude: |
   (?x)(
       ^assets/|
-      ^docs/.*.html
+      ^docs/.*.html|
+      ^_extensions/
    )
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -12,6 +13,7 @@ repos:
       - id: check-added-large-files
       - id: end-of-file-fixer
       - id: trailing-whitespace
+      - id: check-json
   # spell check
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.4

.prettierrc

@@ -1,4 +1,7 @@
 overrides:
-    - files: "*.md"
-      options:
-          tabWidth: 2
+  - files:
+      - "*.md"
+      - "*.cff"
+      - ".prettierrc"
+    options:
+      tabWidth: 2