Skip to content

docs: fill the gaps in the partner pages - #154

Merged
uniqueg merged 3 commits into
mainfrom
docs/82-partner-gaps
Nov 17, 2026
Merged

uniqueg merged 3 commits into
mainfrom
docs/82-partner-gaps

Conversation

@uniqueg

@uniqueg uniqueg commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Summary

Fills the gaps that #82 lists in the partner pages, with the maintainers' answers of 2026-11-17:

  1. Endpoints: not listed per service, to avoid a maintenance burden. "Using the APIs" now names the Cloud Registry (its UI and API) as the source of truth for the deployment's services, their endpoints and the API versions that they report in their service info; "GA4GH Standards" says the same for the versions of the deployed services.
  2. LS Login: new section "Services that use LS Login": proTES (task requests), TRS-Filer (writes), Cloud Registry (writes), WESkit at BIH. Partners get their client ID accepted by writing to the service email. The old Cloud-Registry-only note is generalised.
  3. Test environment: none; use the production services with a test account.
  4. Docs sites: proWES and DRS-Filer are being revived (unarchived 2026-11-16) and get docs sites with the revival; the "archived and unmaintained" notes are replaced. CWL-WES is no longer referenced (table row and Packages entry removed).
  5. Spec versions: TESK row updated to TES 1.1.0 (tesk-api 2.0.0 reports 1.1.0 in its service info); proWES and DRS-Filer catch up with the revival; the product table stays as a reference of what each product implements, with the registry as the source of truth for running services.

Also removes the pointer to the retired CWL demo of 2023 from "Run workflows through TES" and its unused link reference (docs#89 item 2 drops the CWL demonstrator; this file belongs to this PR, so the line goes here and #89's PR doesn't touch it).

Closes #82

Verification

  • python scripts/check_names.py: passes
  • mkdocs build --strict: passes, no warnings
  • pytest: 25 passed, 100% coverage (unchanged)
  • CI: all checks green (CI passed, Read the Docs build, CodeQL, Sourcery).

Declined review findings

  • Sourcery: point partners to prod entries only. Some services of the deployment (e.g., its proTES) report test; the page instead no longer says "production".
  • Sourcery: link the TESK version to a specification file. tesk-api 2.0.0 still pins the TES 1.0.0 commit as a submodule; its 1.1 support is in the code and the release notes.
  • Sourcery: CWL-WES docs site and catch-up plans (two findings). Archived; the maintainers decided that the docs stop referencing it.
  • Sourcery: operator pages still say archived. Fixed in docs: fill the gaps in the Node operator pages #153.

Review

Light lane: docs only. I reviewed the diff myself.

🤖 Generated with Claude Code

Summary by Sourcery

Bring partner and developer documentation up to date with current service discovery, authentication, API-version, and product availability information.

New Features:

  • Document the Cloud Registry as the source of truth for deployed service endpoints and reported API versions.
  • Add partner guidance for LS Login services, client-ID acceptance, and using production services with test accounts.

Enhancements:

  • Update partner documentation to reflect the revival of proWES and DRS-Filer and remove references to archived CWL-WES.
  • Update TESK’s documented TES support to version 1.1.0 and clarify how product references relate to running service information.
  • Remove the retired CWL demo reference from TES workflow guidance.

Documentation:

  • Refresh API, standards, and package documentation with current service discovery, authentication, availability, and documentation status guidance.

Point to the Cloud Registry as the source of truth for services,
endpoints and API versions, list the services that use LS Login and
how partners get their client ID accepted, and say that there is no
test environment. Mark proWES and DRS-Filer as being revived, update
TESK to TES 1.1.0 and drop CWL-WES and the retired CWL demo.

Closes #82

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg uniqueg self-assigned this Nov 17, 2026
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Reviewer's Guide

Documentation

Establish the Cloud Registry as the source of truth for deployed services, endpoints, and reported API versions, while qualifying that manual and out-of-sync entries may be stale.

  • docs/partners-and-developers/apis.md L8 (removed lines), L13-23
  • docs/partners-and-developers/ga4gh-standards.md L12-16

Document the lack of a separate partner test environment and the services that accept LS Login tokens, including how partners request client-ID acceptance.

  • docs/partners-and-developers/apis.md L8-9, L69-88

Update the product reference table and notes for TESK, proWES, and DRS-Filer to reflect their stated API versions and revival status.

  • docs/partners-and-developers/apis.md L123-124
  • docs/partners-and-developers/ga4gh-standards.md L24-30, L46-51
  • docs/partners-and-developers/packages.md L41-45

Remove references to archived CWL-WES and the retired CWL demo from the partner pages and their shared reference links.

  • docs/partners-and-developers/ga4gh-standards.md L86 (removed lines)
  • includes/references.md L6 (removed lines)

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@uniqueg
uniqueg marked this pull request as ready for review November 17, 2026 04:38
@sourcery-ai

sourcery-ai Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Linked issues

Checked at commit 2b7ff10

#82 docs: fill the gaps in the partner pages · 3 of 5 met

# Requirement Status Notes
1 Identify the Cloud Registry as the source for deployed services, endpoints and API versions. ✅ Met The API and standards pages point to the registry, explain which information it provides, and warn that some entries may be out of date.
2 List the services using LS Login, what requires a token, who may call them, and how partners get their client ID accepted. ✅ Met The new table lists the services and token requirements; the page explains client-ID acceptance and links to access rules.
3 Say whether partners have a test environment. ✅ Met The page says there is no separate test environment and directs partners to use the deployment with a test account.
4 Answer whether proWES, DRS-Filer and CWL-WES will get docs sites. 🟡 Partly met The page says proWES and DRS-Filer will get docs sites with their revival, but removes CWL-WES without saying whether it will get a docs site.
5 Address plans to catch up with current GA4GH specification versions. 🟡 Partly met The change updates TESK's version and describes catch-up for proWES and DRS-Filer, but gives no catch-up status for CWL-WES, which it removes from the table.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey - I've found 6 issues

Prompt for AI Agents
Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/partners-and-developers/packages.md" line_range="43-45" />
<code_context>
-  maintained; their READMEs are kept for reference.
+- [proWES](https://github.com/elixir-cloud-aai/proWES): a WES gateway, and
+  [DRS-Filer](https://github.com/elixir-cloud-aai/drs-filer): a DRS service.
+  Both are being revived since 2026-11-16, after they had been archived;
+  they get docs sites with the revival, and until then their READMEs are
+  the docs.

 More services are listed in the [GitHub organization][elixir-on-cloud-github].
</code_context>
<issue_to_address>
**Conflicting revival guidance**

When operators follow the partner pages to the operator service pages, catalog, or onboarding guidance, the operator documentation still labels proWES and DRS-Filer archived and unmaintained and says not to deploy them, contradicting the partner pages' revival guidance and leaving operators unsure whether the services are available.

Update the operator service pages, index, and onboarding guidance to match the revival status in the partner pages.

Also at `docs/partners-and-developers/apis.md:118-119`, `docs/partners-and-developers/ga4gh-standards.md:49-51`.
</issue_to_address>

### Comment 2
<location path="docs/partners-and-developers/apis.md" line_range="14-17" />
<code_context>
-The [Cloud Registry](https://cloud-registry.readthedocs.io/en/latest/) lists
-the services of the deployment. It implements the [GA4GH Service Registry
+The [Cloud Registry](https://cloud-registry.readthedocs.io/en/latest/) of
+the deployment is the source of truth for its services: which services
+run, their endpoints, and the versions of the GA4GH APIs that they
+implement, which the registry reads from the service info of each service
+(`GET /service-info`). These docs don't repeat them. The registry
+implements the [GA4GH Service Registry
 API](https://github.com/ga4gh-discovery/ga4gh-service-registry). Anyone can
</code_context>
<issue_to_address>
**Registry details appear current**

When a registry entry is manual, out of sync, or belongs to Funnel or Poiesis, the registry retains manually entered or last-synced endpoints and API versions rather than reading current values from each service's `/service-info`, so partners can mistake stale details for current ones.

Qualify the guidance to explain that manually entered or out-of-sync registry entries may not reflect current service information.

Also at `docs/partners-and-developers/ga4gh-standards.md:15-16`.
</issue_to_address>

### Comment 3
<location path="docs/partners-and-developers/apis.md" line_range="8-9" />
<code_context>
-    partner gets its client ID accepted, and a test environment. Until then,
-    find the services in the Cloud Registry (step 1) or write to
-    [cloud-service@elixir-europe.org][elixir-on-cloud-email].
+There is no separate test environment for partners: use the production
+services with a test account.

 ## 1. Find the services
</code_context>
<issue_to_address>
**Partners can select nonproduction endpoints**

When the registry contains a service entry whose environment is `test`, when the registry lists a service with environment `test`, the discovery instructions tell partners to choose by API type and call its URL but do not say to select only `prod`. A partner can therefore call a test Node despite being told to use production services.

Tell partners to use only entries marked `prod` and distinguish those from test-Node entries.
</issue_to_address>

### Comment 4
<location path="docs/partners-and-developers/ga4gh-standards.md" line_range="24" />
<code_context>
+| [TESK][tesk] | [TES][ga4gh-tes], for tasks | [1.1.0](https://github.com/elixir-cloud-aai/tesk-api/releases/tag/v2.0.0) (tesk-api 2.0.0) | [1.1.0](https://github.com/ga4gh/task-execution-schemas/releases/tag/v1.1) | [TESK](https://tesk.readthedocs.io/en/latest/) |
</code_context>
<issue_to_address>
**TESK version link skips the specification**

When a partner follows the TESK implemented-version link to verify the specification, the TESK row links its implemented `1.1.0` version to the `tesk-api` release page, not to the API specification or its source commit as the page promises. Partners following the version link cannot inspect the specification that the product builds on.

Link the implemented version to the TES specification file or commit, and keep the `tesk-api` release link as supporting implementation evidence.
</issue_to_address>

### Comment 5
<location path="docs/partners-and-developers/packages.md" line_range="41-44" />
<code_context>
   federates TES services.
 - [TRS-Filer](https://trs-filer.readthedocs.io/en/latest/): a TRS service for
   tools and workflows.
-- [proWES](https://github.com/elixir-cloud-aai/proWES): a WES gateway,
-  [CWL-WES](https://github.com/elixir-cloud-aai/cwl-WES): a WES service for CWL
-  workflows, and [DRS-Filer](https://github.com/elixir-cloud-aai/drs-filer): a
-  DRS service. These three were archived on 2026-11-15 and are no longer
-  maintained; their READMEs are kept for reference.
+- [proWES](https://github.com/elixir-cloud-aai/proWES): a WES gateway, and
</code_context>
<issue_to_address>
**CWL-WES docs status**

The issue asks whether CWL-WES will get a docs site. The change removes CWL-WES from the package list but gives no answer about its docs.
</issue_to_address>

### Comment 6
<location path="docs/partners-and-developers/ga4gh-standards.md" line_range="26" />
<code_context>
-| [CWL-WES](https://github.com/elixir-cloud-aai/cwl-WES) | [WES][ga4gh-wes], for workflows | [1.0.0](https://github.com/elixir-cloud-aai/cwl-WES/blob/dev/cwl_wes/api/20181010.be85140.workflow_execution_service.swagger.yaml) | [1.1.0](https://github.com/ga4gh/workflow-execution-service-schemas/releases/tag/1.1.0) | archived, unmaintained: see the README |
</code_context>
<issue_to_address>
**CWL-WES catch-up status**

The issue asks about plans to catch up with current specifications, including CWL-WES. The change removes its specification-table row without documenting its status or plans.
</issue_to_address>

Sourcery assessment

Approval pending. 5 findings to address first.

Blocking findings: docs/partners-and-developers/packages.md:45, docs/partners-and-developers/apis.md:17, docs/partners-and-developers/apis.md:9, docs/partners-and-developers/packages.md:44, docs/partners-and-developers/ga4gh-standards.md:26


Sourcery is free for open source - if you like our reviews please consider sharing them ✨

Comment thread docs/partners-and-developers/apis.md Resolved
Comment thread docs/partners-and-developers/apis.md Resolved
uniqueg and others added 2 commits November 17, 2026 05:58
Say that manual and out-of-sync entries of the Cloud Registry may be
out of date, and don't call the services of the deployment
"production", as some of them report the environment "test".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@uniqueg
uniqueg merged commit 89b66c3 into main Nov 17, 2026
13 checks passed
@uniqueg
uniqueg deleted the docs/82-partner-gaps branch November 17, 2026 05:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: fill the gaps in the partner pages

1 participant