Skip to content

Commit 3483bbb

Browse files
vsmalladivsmalladi
authored
Merge pull request #219 from ga4gh/develop
Update main to spec standards for 1.1
2 parents 9e9c5aa + c4c17c9 commit 3483bbb

File tree

7 files changed

+652
-146
lines changed

7 files changed

+652
-146
lines changed

‎.github/workflows/build.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Build OpenAPI docs
2+
on:
3+
push:
4+
branches:
5+
- main
6+
- develop
7+
- 'release*'
8+
pull_request:
9+
types: [opened, reopened, sychronize]
10+
jobs:
11+
docs-build:
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Setup Node.js environment
15+
uses: actions/setup-node@v4
16+
with:
17+
node-version: 14.x
18+
# Comes with npm 6. For newer Node, encountered: https://github.com/npm/cli/issues/3359
19+
- run: npm install -g @redocly/openapi-cli && npm install -g redoc-cli
20+
- run: npm install -g gh-openapi-docs
21+
- name: Check out repository code
22+
uses: actions/checkout@v4
23+
- run: gh-openapi-docs
24+
- name: Deploy 🚀
25+
uses: JamesIves/github-pages-deploy-action@v4
26+
with:
27+
branch: gh-pages
28+
folder: .
29+
target-folder: ${{ github.ref == 'refs/heads/main' && 'docs/index.html' || '' }} # Deploy to docs/index.html only if on main
30+
clean: ${{ github.ref == 'refs/heads/main' }} # Clean only if on the main branch

‎.github/workflows/ci.yml‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Lint and validate OpenAPI specs
2+
on:
3+
- push
4+
- pull_request_target
5+
jobs:
6+
lint:
7+
name: Lint OpenAPI definition
8+
runs-on: ubuntu-latest
9+
steps:
10+
- name: Check out head branch
11+
uses: actions/checkout@v4
12+
- name: Run OpenAPI Lint Action
13+
uses: mhiew/redoc-lint-github-action@v4
14+
with:
15+
args: 'openapi/task_execution_service.openapi.yaml'
16+
validate:
17+
name: Validate OpenAPI definition
18+
runs-on: ubuntu-latest
19+
steps:
20+
- name: Check out head branch
21+
uses: actions/checkout@v4
22+
- name: Run OpenAPI Validate Action
23+
uses: swaggerexpert/swagger-editor-validate@v1
24+
with:
25+
definition-file: openapi/task_execution_service.openapi.yaml
26+
27+
diff:
28+
name: Show OpenAPI differences relative to target branch
29+
runs-on: ubuntu-latest
30+
outputs:
31+
diff_generated: ${{ steps.upload-log.outputs.artifact_id }}
32+
steps:
33+
- name: Check out head branch
34+
uses: actions/checkout@v4
35+
with:
36+
ref: ${{ github.ref }}
37+
path: head
38+
- name: Check out base branch
39+
uses: actions/checkout@v4
40+
with:
41+
ref: ${{ github.event.pull_request.base.ref }}
42+
path: base
43+
- name: Create output directory
44+
run: mkdir -p diff-artifacts/
45+
- name: Pull Docker Image
46+
run: docker pull openapitools/openapi-diff:2.0.1
47+
- name: Run openapi-diff tool
48+
run: |
49+
docker run --rm \
50+
-v $(pwd)/head:/head:ro \
51+
-v $(pwd)/base:/base:ro \
52+
-v $(pwd)/diff-artifacts:/local \
53+
openapitools/openapi-diff:2.0.1 \
54+
/base/openapi/task_execution_service.openapi.yaml \
55+
/head/openapi/task_execution_service.openapi.yaml \
56+
--markdown /local/diff.md 2> diff-artifacts/error.log
57+
- name: Get PR number
58+
id: get-pr-number
59+
run: |
60+
echo "${{ github.event.pull_request.number }}" > diff-artifacts/pr_number
61+
- name: Upload artifacts
62+
uses: actions/upload-artifact@v4
63+
with:
64+
name: diff-artifacts
65+
path: diff-artifacts/
66+
if-no-files-found: ignore
67+
- name: Check if OpenAPI Diff failed
68+
id: check-diff
69+
run: |
70+
if [ -s diff-artifacts/error.log ]; then
71+
echo "The diff failed. Please see artifact error.log."
72+
exit 1
73+
fi
74+
75+
permissions:
76+
contents: read
77+
pull-requests: write
78+
issues: write

‎.travis.yml‎

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎CONTRIBUTING.md‎

Lines changed: 38 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,47 @@
11

22
# CONTRIBUTING
33

4-
This schema is developed by the [Cloud Work Stream](https://ga4gh.cloud) of the [Global Alliance for Genomics and Health](https://ga4gh.org).
4+
This schema is developed by the [Cloud Work
5+
Stream]([https://ga4gh.cloud](https://www.ga4gh.org/work_stream/cloud/)) of the
6+
[Global Alliance for Genomics and Health](https://ga4gh.org).
57

68
## Semantic Versioning
79

8-
We use [semantic versioning](https://semver.org/) for TES, this will determine if your proposed changes impact a major or minor release.
10+
The Task Execution Service (TES) API uses [semantic
11+
versioning](https://semver.org/) for TES. Please consider that breaking changes
12+
imply a new major version release, which is associated with considerable
13+
administrative work and therefore happen only rarely.
914

1015
## Suggesting Changes
1116

12-
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.
13-
14-
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.
15-
16-
> 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>/`:
17-
18-
+ https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/docs/
19-
+ https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger-ui/
20-
+ https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger.json
21-
+ https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger.yaml
22-
23-
> Providing this base URL in the pull request comment is appreciated, but not required.
24-
25-
If a security vulnerability is identified with the specification please send an email to security-notification@ga4gh.org detailing your concerns.
26-
27-
## Approving Changes
28-
29-
### pre-TES v1.0.0 / Testbed Voting Procedure
30-
Changes for the release are to be approved by 2 TES specification leads.
31-
32-
### post TES v1.0.0 Voting Procedure
33-
The post v1.0.0 voting group include stakeholders, such as server and client implementors.
34-
The membership of this group will be established as part of the v1.0.0 release.
17+
Changes to TES can be initiated as
18+
[**issues**](https://github.com/ga4gh/task-execution-schemas/issues) or
19+
[**pull requests**](https://github.com/ga4gh/task-execution-schemas/pulls) to
20+
allow for discussion and review. For considerable changes, we generally
21+
recommend opening issues first in order to discuss scope and feasibility.
22+
23+
When creating pull requests, please do so from your own fork - even if you have
24+
write access to the repository. In this way, when the main repository is forked
25+
again, the new fork is created with a minimum of extraneous, volatile branches.
26+
27+
> To facilitate the review of external pull requests, users are encouraged to
28+
> activate [**GitHub Actions**](https://github.com/features/actions) to monitor
29+
> the build status of their fork. By following the documentation for [deployment
30+
> to GitHub
31+
> Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site),
32+
> pushes to the forked repository will be viewable at
33+
> `https://[user-or-org].github.io/task-execution-service/preview/<branch>/`,
34+
> e.g.,:
35+
> - `https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/docs/`
36+
> - `https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger-ui/`
37+
> - `https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger.json`
38+
> - `https://[user-or-org].github.io/task-execution-schemas/preview/\<branch\>/swagger.yaml`
39+
40+
Providing this base URL in the pull request comment is appreciated, but not
41+
required.
42+
43+
If a security vulnerability is identified with the specification, please send an
44+
email to <mailto:security-notification@ga4gh.org> detailing your concerns.
45+
46+
For more information please refer to the [**governance
47+
documentation**](GOVERNANCE.md).

‎GOVERNANCE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
TES Governance and Process
2+
==============================
3+
4+
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.
5+
6+
Current TES Product Leads are:
7+
8+
| Name | Organization | github |
9+
|:-------------------|:-------------|:------------------
10+
| Kyle Ellrot | [Oregon Health and Science University](https://www.ohsu.edu/) | [kellrott](https://github.com/kellrott) |
11+
| Venkat Malladi | [Microsoft](https://www.microsoft.com/en-us/genomics/) | [vsmalladi](https://github.com/vsmalladi) |
12+
| Alex Kanitz | [Swiss Institute of Bioinformatics / ELIXIR Switzerland](https://www.sib.swiss/) | [uniqueg](https://github.com/uniqueg) |
13+
14+
15+
## Voting Procedure
16+
17+
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:ga4gh-cloud-tes+subscribe@ga4gh.org) 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.
18+
19+
Sign up for the [**GA4GH TES API mailing list**](mailto:ga4gh-cloud-tes+subscribe@ga4gh.org) 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.

0 commit comments

Comments
 (0)