Add workflow for testing downstream packages (#7)

Author: mtfishman

.github/workflows/IntegrationTest.yml

@@ -0,0 +1,69 @@
+name: "Reusable IntegrationTest Workflow"
+
+on:
+  workflow_call:
+    inputs:
+      julia-version:
+        description: "Julia version"
+        default: "1"
+        required: false
+        type: string
+      repo:
+        description: "Repository name, including the group/user, such as ITensor/ITensors.jl"
+        required: true
+        type: string
+      local-registry-urls:
+        description: 'Registries besides General to use. Specified by providing the url (https/ssh) to the Github
+                      repositories as a newline (\n) seperated list. Defaults to including the ITensorRegistry
+                      (https://github.com/ITensor/ITensorRegistry.git).'
+        default: ""
+        required: false
+        type: string
+
+jobs:
+  test:
+    name: ${{ inputs.repo }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: ${{ inputs.julia-version }}
+          arch: x64
+          localregistry: https://github.com/ITensor/ITensorRegistry.git
+      - uses: julia-actions/julia-buildpkg@latest
+      - name: Clone Downstream
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ inputs.repo }}
+          path: downstream
+      - name: Load this and run the downstream tests
+        shell: julia --color=yes --project=downstream {0}
+        run: |
+          using Pkg
+          # If provided add local registries
+          if !isempty("${{ inputs.local-registry-urls }}")
+            registry_urls = split("${{ inputs.local-registry-urls }}", "\n") .|> string
+            for registry_url in registry_urls
+              isempty(registry_url) && continue
+              Pkg.Registry.add(Pkg.RegistrySpec(; url=registry_url))
+            end
+          end
+          try
+            # force it to use this PR's version of the package
+            Pkg.develop(PackageSpec(path="."))  # resolver may fail with main deps
+            Pkg.update()
+            Pkg.test(coverage=true)  # resolver may fail with test time deps
+          catch err
+            err isa Pkg.Resolve.ResolverError || rethrow()
+            # If we can't resolve that means this is incompatible by SemVer and this is fine
+            # It means we marked this as a breaking change, so we don't need to worry about
+            # Mistakenly introducing a breaking change, as we have intentionally made one
+            @info "Not compatible with this release. No problem." exception=err
+            exit(0)  # Exit immediately, as a success
+          end

README.md

@@ -207,3 +207,41 @@ jobs:
     with:
       local-registry-urls: "https://github.com/ITensor/ITensorRegistry.git"
 ```
+
+## IntegrationTest
+
+Test a set of dependencies of the package against the current PR branch
+to check if changes in the branch break any downstream tests. If the version
+is bumped to indicate a breaking change according to semver, the test passes
+since it is safe to register the changes without breaking downstream
+packages if they follow semver in their compat versions.
+Additionally, if some dependent packages being tested are registered in one or more
+local registry, you can specify a list of local registries using their
+repository URLs using the `local-registy-urls` option,
+which should be a string with registry URLs seperated by a newline character (`\n`).
+Here is an example workflow:
+
+```yaml
+name: "IntegrationTest"
+
+on:
+  push:
+    branches:
+      - 'main'
+    tags: '*'
+  pull_request:
+
+jobs:
+  integration-test:
+    name: "IntegrationTest"
+    strategy:
+       matrix:
+         repo:
+           - 'ITensor/BlockSparseArrays.jl'
+           - 'ITensor/NamedDimsArrays.jl'
+           - 'ITensor/TensorAlgebra.jl'
+    uses: "ITensor/ITensorActions/.github/workflows/IntegrationTest.yml@main"
+    with:
+      local-registry-urls: "https://github.com/ITensor/ITensorRegistry.git"
+      repo: "${{ matrix.repo }}"
+```