Merge pull request #367 from sneakers-the-rat/testing-upstream-branch

Specify repo and branch when testing against upstream

Author: amc-corey-cox

.github/workflows/test-upstream.yaml

@@ -4,10 +4,20 @@ on:
     branches:
       - main
   workflow_dispatch:
+    inputs:
+      upstream_repo:
+        description: "Upstream linkml repository to test against"
+        required: true
+        default: "linkml/linkml"
+      upstream_branch:
+        description: "Upstream linkml branch to test against"
+        required: true
+        default: "main"
 
 jobs:
   test_upstream:
     strategy:
+      fail-fast: false
       matrix:
         os: [ ubuntu-latest, windows-latest ]
         python-version: [ "3.8", "3.9", "3.10", "3.11", "3.12" ]
@@ -23,13 +33,61 @@ jobs:
       POETRY_VIRTUALENVS_IN_PROJECT: true
 
     steps:
+      - name: Get upstream branch and repo from first lines of PR Body
+        if: github.event_name == 'pull_request'
+        shell: bash
+        env:
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          set +e
+          set +o pipefail
+          
+          UPSTREAM_BRANCH=$( \
+            echo "$PR_BODY" | \
+            head -2 | \
+            grep upstream_branch | \
+            cut -d ":" -f 2 | \
+            awk '{$1=$1};1' \
+          )
+          echo "Got upstream branch:"
+          echo $UPSTREAM_BRANCH
+          
+          if [[ -z "$UPSTREAM_BRANCH" ]]; then
+            echo "Using main as default"
+            UPSTREAM_BRANCH="main"
+          fi
+          
+          UPSTREAM_REPO=$( \
+            echo "$PR_BODY" | \
+            head -2 | \
+            grep upstream_repo | \
+            cut -d ":" -f 2 | \
+            awk '{$1=$1};1' \
+          )
+          echo "Got upstream repo:"
+          echo $UPSTREAM_REPO
+          
+          if [[ -z "$UPSTREAM_REPO" ]]; then
+            echo "Using linkml/linkml as default"
+            UPSTREAM_REPO="linkml/linkml"
+          fi
+
+          echo "upstream_branch=$UPSTREAM_BRANCH" >> "$GITHUB_ENV"
+          echo "upstream_repo=$UPSTREAM_REPO" >> "$GITHUB_ENV"
+
+      - name: Get upstream branch from workflow dispatch
+        if: github.event_name == 'workflow_dispatch'
+        shell: bash
+        run: |
+          echo "upstream_branch=${{ inputs.upstream_branch }}" >> "$GITHUB_ENV"
+          echo "upstream_repo=${{ inputs.upstream_repo }}" >> $GITHUB_ENV"
 
       - name: checkout upstream
         uses: actions/checkout@v4
         with:
-          repository: linkml/linkml
+          repository: "${{ env.upstream_repo }}"
           path: linkml
-          ref: main
+          ref: "${{ env.upstream_branch }}"
           fetch-depth: 0
 
       - name: checkout linkml-runtime
@@ -40,7 +98,14 @@ jobs:
           path: linkml-runtime
           fetch-depth: 0
 
-      - name: Ensure tags if not run from main repo
+      - name: Ensure tags for linkml upstream if a different one than linkml/linkml is specified
+        if: "${{ env.upstream_repo != 'linkml/linkml' }}"
+        working-directory: linkml
+        run: |
+          git remote add upstream https://github.com/linkml/linkml
+          git fetch upstream --tags
+
+      - name: Ensure tags for linkml-runtime if not run from main repo
         if: github.repository != 'linkml/linkml-runtime'
         working-directory: linkml-runtime
         run: |
@@ -68,7 +133,7 @@ jobs:
       # make extra sure we're removing any old version of linkml-runtime that exists
       - name: uninstall potentially cached linkml-runtime
         working-directory: linkml
-        run: poetry run pip uninstall linkml-runtime
+        run: poetry run pip uninstall -y linkml-runtime
 
       # we are not using linkml-runtime's lockfile, but simulating what will happen
       # when we merge this and update linkml's lockfile

CONTRIBUTING.md

@@ -31,6 +31,39 @@ ALSO NOTE: github.com lets you create a pull request from the main branch, autom
 
 > A code review (which happens with both the contributor and the reviewer present) is required for contributing.
 
+## Pull Requests
+
+### Upstream Testing
+
+`linkml-runtime` is tightly coupled to upstream `linkml`, 
+so all pull requests have their changes tested by running the upstream tests
+against the PR version of `linkml-runtime`.
+
+In some circumstances, paired changes need to be made against *both*
+`linkml` and `linkml-runtime`, where testing against the `main` branch
+of `linkml` is insufficient. 
+
+When opening a pull request, you can specify that your PR needs to be
+tested against a specific upstream branch and repository by specifying it
+in the first two lines of your pull request like this:
+
+> upstream_repo: my-cool-username/linkml
+> upstream_branch: some-complicated-feature
+> 
+> Hey everyone what up it's me your boy MC spongebob here with another banger
+> ... (PR continues)
+
+The order of the `upstream_repo` and `upstream_branch` tags doesn't matter,
+but they must be on the first two lines of the pull request comment and separated with a colon.
+
+Maintainers can also specify upstream branches to test against when 
+dispatching the `test-upstream` workflow manually via the GUI prompt.
+
+Testing against an unverified upstream branch is not necessarily dangerous,
+since the [input is stored as a variable first and not executed as untrusted code](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable),
+but maintainers should take care to verify that the upstream branch and repo
+are correct and expected given the context of the PR.
+
 ## Development environment setup
 
 1. Install [poetry](https://python-poetry.org/docs/#installation).
@@ -70,7 +103,21 @@ All code added to the linkml-runtime source must have tests. The repo uses the n
 You can run the test suite in the following way:
 
 ```
-poetry run python -m unittest discover
+poetry run python -m pytest
+```
+
+### Upstream Testing
+
+To run the upstream `linkml` tests against your branch,
+install `linkml` locally with poetry, and then manually install your
+local copy of `linkml-runtime`
+
+```shell
+git clone https://github.com/linkml/linkml
+cd linkml
+poetry install --all-extras --with tests
+poetry run pip install -e ~/location/of/linkml-runtime
+poetry run pytest
 ```
 
 ## Code style