fractional resource requirements for CWL 1.1 and 1.2 spec

.github/workflows/build-docs.yml → .github/workflows/build.yml

@@ -1,26 +1,29 @@
 name: Build OpenAPI docs
-on: 
-  - push
-  # - pull_request
+on:
+  push:
+    branches:
+      - main
+      - develop
+      - 'release*'
+  pull_request:
+      types: [opened, reopened, sychronize]
 jobs:
   docs-build:
     runs-on: ubuntu-latest
-    # env:
-    #   TRAVIS_BRANCH: ${{ github.event.number }} 
-    #   a trick that builds docs for PRs (with PR number). Does not work for PRs from forks.
     steps:
       - name: Setup Node.js environment
-        uses: actions/setup-node@v2.5.1
-        with: 
+        uses: actions/setup-node@v4
+        with:
           node-version: 14.x
           # Comes with npm 6. For newer Node, encountered: https://github.com/npm/cli/issues/3359
       - run: npm install -g @redocly/openapi-cli && npm install -g redoc-cli
       - run: npm install -g gh-openapi-docs
       - name: Check out repository code
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
       - run: gh-openapi-docs
       - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@v4.2.2
+        uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages
+          clean: true  # Clean only if on the main branch
           folder: .

.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+name: Lint and validate OpenAPI specs
+on:
+  - push
+  - pull_request_target
+jobs:
+  lint:
+    name: Lint OpenAPI definition
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out head branch
+        uses: actions/checkout@v4
+      - name: Run OpenAPI Lint Action
+        uses: mhiew/redoc-lint-github-action@v4
+        with:
+          args: 'openapi/task_execution_service.openapi.yaml'
+  validate:
+    name: Validate OpenAPI definition
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out head branch
+        uses: actions/checkout@v4
+      - name: Run OpenAPI Validate Action
+        uses: swaggerexpert/swagger-editor-validate@v1
+        with:
+          definition-file: openapi/task_execution_service.openapi.yaml
+
+  diff:
+    name: Show OpenAPI differences relative to target branch
+    runs-on: ubuntu-latest
+    outputs:
+      diff_generated: ${{ steps.upload-log.outputs.artifact_id }}
+    steps:
+      - name: Check out head branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref }}
+          path: head
+      - name: Check out base branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.ref }}
+          path: base
+      - name: Create output directory
+        run: mkdir -p diff-artifacts/
+      - name: Pull Docker Image
+        run: docker pull openapitools/openapi-diff:2.0.1
+      - name: Run openapi-diff tool
+        run: |
+          docker run --rm \
+          -v $(pwd)/head:/head:ro \
+          -v $(pwd)/base:/base:ro \
+          -v $(pwd)/diff-artifacts:/local \
+          openapitools/openapi-diff:2.0.1 \
+          /base/openapi/task_execution_service.openapi.yaml \
+          /head/openapi/task_execution_service.openapi.yaml \
+          --markdown /local/diff.md 2> diff-artifacts/error.log
+      - name: Get PR number
+        id: get-pr-number
+        run: |
+          echo "${{ github.event.pull_request.number }}" > diff-artifacts/pr_number
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: diff-artifacts
+          path: diff-artifacts/
+          if-no-files-found: ignore
+      - name: Check if OpenAPI Diff failed
+        id: check-diff
+        run: |
+          if [ -s diff-artifacts/error.log  ]; then
+            echo "The diff failed. Please see artifact error.log."
+            exit 1
+          fi
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write

CONTRIBUTING.md

@@ -1,34 +1,47 @@
 
 # CONTRIBUTING
 
-This schema is developed by the [Cloud Work Stream](https://ga4gh.cloud) of the [Global Alliance for Genomics and Health](https://ga4gh.org).
+This schema is developed by the [Cloud Work
+Stream]([https://ga4gh.cloud](https://www.ga4gh.org/work_stream/cloud/)) of the
+[Global Alliance for Genomics and Health](https://ga4gh.org).
 
 ## Semantic Versioning
 
-We use [semantic versioning](https://semver.org/) for TES, this will determine if your proposed changes impact a major or minor release.
+The Task Execution Service (TES) API uses [semantic
+versioning](https://semver.org/) for TES. Please consider that breaking changes
+imply a new major version release, which is associated with considerable
+administrative work and therefore happen only rarely.
 
 ## Suggesting Changes
 
-Suggested changes to this schema can be initiated as [**Issues**](https://github.com/ga4gh/task-execution-schemas/issues) or [**Pull Requests**](https://github.com/ga4gh/task-execution-schemas/pulls) to allow for discussion and review.
-
-Even those with write access to the main repository should in general create pull request branches within their own forks. This way when the main repository is forked again, the new fork is created with a minimum of extraneous volatile branches.
-
-> To facilitate review of external pull requests, users are encouraged to activate [**Travis CI**](https://travis-ci.org/) to monitor the build status (documentation, Swagger UI) of their fork. By following the documentation for [deployment to GitHub Pages](https://docs.travis-ci.com/user/deployment/pages/) and adding a `$GITHUB_TOKEN` environment variable to their repo configuration, pushes to the forked repo should be viewable relative to `https://[user-or-org].github.io/workflow-execution-service-schemas/preview/<branch>/`:
-
-+ https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/docs/
-+ https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger-ui/
-+ https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger.json
-+ https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger.yaml
-
-> Providing this base URL in the pull request comment is appreciated, but not required.
-
-If a security vulnerability is identified with the specification please send an email to [email protected] detailing your concerns.
-
-## Approving Changes
-
-### pre-TES v1.0.0 / Testbed Voting Procedure
-Changes for the release are to be approved by 2 TES specification leads.
-
-### post TES v1.0.0 Voting Procedure
-The post v1.0.0 voting group include stakeholders, such as server and client implementors.
-The membership of this group will be established as part of the v1.0.0 release.
+Changes to TES can be initiated as
+[**issues**](https://github.com/ga4gh/task-execution-schemas/issues) or
+[**pull requests**](https://github.com/ga4gh/task-execution-schemas/pulls) to
+allow for discussion and review. For considerable changes, we generally
+recommend opening issues first in order to discuss scope and feasibility.
+
+When creating pull requests, please do so from your own fork - even if you have
+write access to the repository. In this way, when the main repository is forked
+again, the new fork is created with a minimum of extraneous, volatile branches.
+
+> To facilitate the review of external pull requests, users are encouraged to
+> activate [**GitHub Actions**](https://github.com/features/actions) to monitor
+> the build status of their fork. By following the documentation for [deployment
+> to GitHub
+> Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site),
+> pushes to the forked repository will be viewable at
+> `https://[user-or-org].github.io/task-execution-service/preview/<branch>/`,
+> e.g.,:
+> - `https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/docs/`
+> - `https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger-ui/`
+> - `https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger.json`
+> - `https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger.yaml`
+
+Providing this base URL in the pull request comment is appreciated, but not
+required.
+
+If a security vulnerability is identified with the specification, please send an
+email to <mailto:[email protected]> detailing your concerns.
+
+For more information please refer to the [**governance
+documentation**](GOVERNANCE.md).

GOVERNANCE.md

@@ -0,0 +1,19 @@
+TES Governance and Process
+==============================
+
+The Task Execution Service (TES) operates under a community-driven development model, where advancements to the specification occur exclusively through community contributions. The standard is governed by a core team of Product Leads that fosters collaboration and consensus among contributors. This team is tasked with overseeing the design and development processes, setting priorities, managing the release schedule, and making decisions in instances where consensus cannot be reached.
+
+Current TES Product Leads are:
+
+| Name               | Organization       | github                  |
+|:-------------------|:-------------|:------------------
+| Kyle Ellrot        | [Oregon Health and Science University](https://www.ohsu.edu/) | [kellrott](https://github.com/kellrott) |
+| Venkat Malladi     | [Microsoft](https://www.microsoft.com/en-us/genomics/)        | [vsmalladi](https://github.com/vsmalladi) |
+| Alex Kanitz        | [Swiss Institute of Bioinformatics / ELIXIR Switzerland](https://www.sib.swiss/)        | [uniqueg](https://github.com/uniqueg) |
+
+
+## Voting Procedure
+
+Proposed changes and releases are voted on by Driver Project champions and other key stakeholders, such as product implementers (client- and sever-side). Product Leads review proposed changes on a regular product-specific call, then solicit community feedback during regular Cloud Work Stream calls and through the [product-specific](mailto:[email protected]) mailing list for a specified time period. Proposed releases are further shared through official GA4GH channels (Slack board and mailing list with wider scope) and with a longer feedback period. Product Leads, in close connection with the Cloud Work Stream leadership, will always strive to reach broad consensus, but may accept simple majority decisions if broad consensus cannot be reached.
+
+Sign up for the [**GA4GH TES API mailing list**](mailto:[email protected]) to stay updated about the latest news and developments around the TES API, in particular for soliciting comments on proposed specification changes and for notifications about TES subgroup meetings.