Merge branch 'main' into dependabot/pip/ruff-0.6.3

.github/actions/is-release/action.yml

@@ -0,0 +1,39 @@
+name: Check if PR is a release
+description: "Checks if the PR is a release"
+
+outputs:
+  is_release:
+    description: "Is this a release?"
+    value: ${{ steps.check_if_release.outputs.is_release }}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Check if PR is a release
+      shell: bash
+      id: check_if_release
+      continue-on-error: true
+      run: |
+        # Get the diff between the current commit and the last merge commit on the upstream/main branch
+        git remote add upstream https://github.com/hyperledger/aries-cloudagent-python.git
+        git fetch upstream
+        
+        last_merge=$(git rev-list --no-merges -n 1 upstream/main)
+        
+        echo event = ${{ github.event_name }}
+
+        echo last upstream commit = "$last_merge"
+        echo current pr commit = "${{ github.sha }}"
+
+        echo Will exit with code 1 if the pull request is not a release
+
+        changes=$(git diff "${{ github.sha }}" "$last_merge" pyproject.toml)
+
+        # Extract the version of aries-cloudagent from the diff of pyproject.toml
+        version=$(echo "$changes" | grep -A1 'name = "aries_cloudagent"' | head -n 2 | tail -n 1 | awk '{print $3}' | tr -d '"')
+
+        echo "$version"
+        if [ "$version" ]; then
+          echo "This is a release because the aries-cloudagent version in pyproject.toml has changes"
+          echo is_release=true >> $GITHUB_OUTPUT
+        fi

.github/workflows/bdd-integration-tests.yml

@@ -29,37 +29,13 @@ jobs:
         with:
           fetch-depth: 0
       - name: Check if PR is a release
+        uses: ./.github/actions/is-release
         id: check_if_release
-        continue-on-error: true
-        run: |
-          # Get the diff between the current commit and the last merge commit on the upstream/main branch
-          git remote add upstream https://github.com/hyperledger/aries-cloudagent-python.git
-          git fetch upstream
-          
-          last_merge=$(git rev-list --no-merges -n 1 upstream/main)
-          
-          echo event = ${{ github.event_name }}
-
-          echo last upstream commit = "$last_merge"
-          echo current pr commit = "${{ github.sha }}"
-
-          echo Will exit with code 1 if the pull request is not a release
-
-          changes=$(git diff "${{ github.sha }}" "$last_merge" pyproject.toml)
-
-          # Extract the version of aries-cloudagent from the diff of pyproject.toml
-          version=$(echo "$changes" | grep -A1 'name = "aries_cloudagent"' | head -n 2 | tail -n 1 | awk '{print $3}' | tr -d '"')
-
-          echo "$version"
-          if [ "$version" ]; then
-            echo "This is a release because the aries-cloudagent version in pyproject.toml has changes"
-            echo is_release=true >> $GITHUB_OUTPUT
-          fi
-      - name: run-pr-integration-tests
+      - name: Run PR or Nightly Integration Tests
         uses: ./.github/actions/run-integration-tests
-        if: (steps.check_if_release.outputs.is_release != 'true' && github.event_name == 'pull_request')
-      - name: run-release-or-cron-integration-tests
-        if: (steps.check_if_release.outputs.is_release == 'true' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch')
+        if: (steps.check_if_release.outputs.is_release != 'true')
+      - name: Run Release Integration Tests
+        if: (steps.check_if_release.outputs.is_release == 'true')
         uses: ./.github/actions/run-integration-tests
         with:
           TEST_SCOPE: "-t @Release -t ~@BBS"

.github/workflows/bdd-interop-tests.yml

@@ -1,6 +1,9 @@
 name: BDD Interop Integration Tests
 
 on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
   pull_request:
     branches:
       - main
@@ -25,14 +28,17 @@ jobs:
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
+      - name: Check if PR is a release
+        uses: ./.github/actions/is-release
+        id: check_if_release
       - name: Request GitHub API for PR data
         uses: octokit/[email protected]
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         id: get_pr_data
         with:
           route: GET /repos/${{ github.event.repository.full_name }}/pulls/${{ github.event.number }}
-      - name: Run BDD Interop Tests
+      - name: Prepare Interop Tests
         run: |
           # Get AATH 
           git clone https://github.com/hyperledger/aries-agent-test-harness.git
@@ -42,5 +48,14 @@ jobs:
           cat aries-agent-test-harness/aries-backchannels/acapy/requirements-main.txt
           cd aries-agent-test-harness
           ./manage build -a acapy-main
+      - name: Run PR Interop Tests
+        if: (steps.check_if_release.outputs.is_release != 'true' && github.event_name == 'pull_request')
+        run: |
+          cd aries-agent-test-harness
           NO_TTY=1 LEDGER_URL_CONFIG=http://test.bcovrin.vonx.io TAILS_SERVER_URL_CONFIG=https://tails.vonx.io ./manage run -d acapy-main -t @critical -t ~@wip -t ~@T004-RFC0211 -t ~@DidMethod_orb -t ~@Transport_NoHttpOutbound
+      - name: Run Release or Nightly Interop Tests
+        if: (steps.check_if_release.outputs.is_release == 'true' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch')
+        run: |
+          cd aries-agent-test-harness
+          NO_TTY=1 LEDGER_URL_CONFIG=http://test.bcovrin.vonx.io TAILS_SERVER_URL_CONFIG=https://tails.vonx.io ./manage run -d acapy-main -t @AcceptanceTest -t ~@wip -t ~@T004-RFC0211 -t ~@DidMethod_orb -t ~@Transport_NoHttpOutbound
 

.github/workflows/scenario-integration-tests.yml

@@ -1,6 +1,9 @@
 name: Scenario Integration Tests
 
 on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
   pull_request:
     branches:
       - main

Managing-ACA-Py-Doc-Site.md

@@ -0,0 +1,135 @@
+# Managing the ACA-Py Documentation Site
+
+The ACA-Py documentation site is a [MkDocs Material] site generated from the
+Markdown files in this repository. Whenever the `main` branch is updated or a
+release branch is (possibly temporarily) created, the [publish-docs] GitHub
+Action is fired, generating and publishing the documentation for the
+updated/created branch. The generation process generates the static set of HTML
+pages for the version in a folder in the `gh-pages` branch of this repo. The
+static pages for each (other than the `main` branch) version are not updated
+after creation. From time to time, some "extra" maintenance on the versions are
+needed and this document describes those activities.
+
+[MkDocs Material]: https://squidfunk.github.io/mkdocs-material/
+[publish-docs]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/.github/workflows/publish-docs.yml
+
+## Generation Process
+
+The generation process includes the following steps as part of the GitHub Action
+and mkdocs configuration.
+
+When the GitHub Action fires, it runs a container that carries out the following steps:
+
+- Checks out the triggering branch, either `main` or `docs-v<version>` (e.g `docs-v1.0.0`).
+- Runs the script [scripts/prepmkdocs.sh], which moves and updates some of the
+  markdown files so that they fit into the generated site. See the comments in
+  the scripts for details about the copying and editing done via the script. In
+  general, the copying of files is to put markdown files in the root folder into
+  the `docs` folder, and to update links that need to be changed to work on the
+  generated site. This allows us to have links working using the GitHub UI and
+  on the generated site.
+- Invokes the mkdocs extension `mike` that generates the mkdocs HTML pages and
+  then captures and commits them into the `gh-pages` branch of the repository.
+  It also adds (if needed) a reference to the new version in the site's
+  "versions" dropdown, enabling users to pick the version of the docs they want
+  to look at. The process uses the [mkdocs.yml] configuration file in generating
+  the site.
+
+[scripts/prepmkdocs.sh]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/scripts/prepmkdocs.sh
+[mkdocs.yml]: https://github.com/hyperledger/aries-cloudagent-python/blob/main/mkdocs.yml
+
+## Preparing for a Release
+
+When preparing for a release (or even just a PR to `main`) you can test the
+documentation site on your local clone using the following steps. The steps
+assume that you have installed `mkdocs` on your system. Guidance for that can be
+found in the [MkDocs Material] documentation.
+
+- Note the files changed in your repository that have not been committed. This
+  process will change and then "unchange" files in your local clone. The
+  "unchange" may not be perfect, so you want to be sure that no extra changed
+  files get into your next commit.
+- Run the bash script [scripts/prepmkdocs.sh]. It will change a number of files
+  in your local repository.
+- Run `mkdocs`. Watch for warnings of missing documents and broken links in the
+  startup messages. See the notes below for dealing with those issues.
+- Open your browser and browse the site, looking for any issues.
+- Update the documents, [mkdocs.yml] and the [scripts/prepmkdocs.sh] as needed,
+  repeating the generation process as needed.
+- When you are happy run [scripts/prepmkdocs.sh] with the parameter `clean`.
+  This should undo the changes done by the script. You should check that there
+  no unexpected files changed that you don't want committed into the repo.
+
+If there are missing documents, it may be that they are new Markdown files that
+have not yet been added to the [mkdocs.yml] navigation. Update that file to add
+the new files, and push the changes to the repository in a pull request. There
+are a few files listed below that we don't generate into the documentation site,
+and they can be ignored.
+
+- `assets/README.md`
+- `design/AnoncredsW3CCompatibility.md`
+- `design/UpgradeViaApi.md`
+- `features/W3cCredentials.md`
+
+If there are broken links, it is likely because there is a Markdown link that
+works using the GitHub UI (e.g. a relative link to a file in the repo) but
+doesn't on the generated site. In general there are two ways to fix these:
+
+- Change the link in the Markdown file so that it is a fully qualified URL vs. a
+  relative link, so that it works in both the GitHub UI and the generated site.
+- Extend the [scripts/prepmkdocs.sh] `sed` commands so that the link differs in
+  the GitHub UI and the generated site -- working in both. A pain, but sometimes
+  needed...
+
+## Removing RC Releases From the Generated Site
+
+Documentation is added to the site for release candidates (RCs). When those
+release candidates are replaced, we want to remove their documentation version
+from the documentation site. In the current GitHub Action, the version
+documentation is created but never deleted, so the process to remove the
+documentation for the RC is manual. It would be nice to create a mechanism in
+the GitHub Action to do this automatically, but its not there yet.
+
+To delete the documentation version, do the following:
+
+- In your local fork, checkout the gh-pages: `git checkout -b gh-pages --track
+  upstream/gh-pages` (or use whatever local branch name you want)
+- Check your `git status` and make sure there are no changes in the branch --
+  e.g., new files that shouldn't be added to the `gh-pages` branch. If there are
+  any -- delete the files so they are not added.
+- Remove the folder for the RC.  For example `rm -rf 1.0.0rc4`
+- Edit the `versions.json` file and remove the reference to the RC release in
+  the file.
+- Push the changes via a PR to the ACA-Py `gh-pages` branch (don't PR them into
+  `main`!!).
+- Merge the PR and verify (after a few minutes) that the drop down no longer has
+  the RC in it.
+
+## Adding new 0.11.x Releases
+
+The automatic generation process from ACA-Py started with release 0.12.0.
+Unfortunately, we declared release 0.11.x to be an Long Term Support version and
+so we still need to add 0.11.x version documentation to the generated site.
+Here's the (lousy) process to do this. Typically, [swcurran] will do this and no
+one else needs to worry about it. But for completeness, here is the process:
+
+- Follow the instructions in the [aries-acapy-docs] repository to generate and
+  publish the documentation site for the new 0.11.x version.
+- Have a local copy of the [aries-acapy-docs] repository. In that repo, run `git
+  checkout -b gh-pages --track upstream/gh-pages` to checkout a local copy of
+  the generated pages from that repo.
+- In ACA-Py, run `git checkout -b gh-pages --track upstream/gh-pages` to create
+  a local branch from which you will push a PR.
+- Copy the v0.11.x folder from [aries-acapy-docs] local to a new 0.11.x folder
+  in the ACA-Py local. Note the "v" that is on the folder in [aries-acapy-docs],
+  but not in ACA-Py.
+- Edit the `versions.json` file to add the 0.11.x reference into the file.
+- Push the changes via a PR to the ACA-Py `gh-pages` branch (don't PR them into
+  `main`!!).
+- Merge the PR and verify (after a few minutes) that the drop down includes the
+  0.11.x version.
+
+Ugly! The LTS for 0.11 ends in January 2025 and this process can be dropped.
+
+[swcurran]: https://github.com/swcurran
+[aries-acapy-docs]: https://github.com/hyperledger/aries-acapy-docs