VERSIONING and TEMPLATE specifications changed, additionally a file for LLM interations has been created #792
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR adds extensive SDRF‑Proteomics documentation and template assets (YAML and SDRF TSV examples), introduces a comprehensive VERSIONING.adoc policy, adds an llms.txt discovery file and README badge, updates many template README links to point to the external sdrf-templates repository, and deletes the LinkML schema file Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@README.md`:
- Line 10: The llms.txt badge link in the README points to a non-existent path;
update the URL target for the badge (the markdown beginning with
[] to either the correct absolute GitHub repo path or a relative
path to llms.txt in this repository so the CI link checker passes; ensure the
displayed badge text and target file name "llms.txt" remain unchanged and verify
the new link resolves in the repo.
In `@sdrf-proteomics/VERSIONING.adoc`:
- Around line 138-164: The text is contradictory: the community template rules
require a spec_compatibility declaration (spec_compatibility) but the
deprecation policy section claims there is no spec_compatibility metadata;
update the document to be consistent by either (A) keeping the community rule
and removing the sentence "There is no `deprecated:` flag, no
`spec_compatibility:` range..." (or rewording it to say spec_compatibility is
required for community templates only), or (B) removing the community-rule
requirement for `spec_compatibility` and instead describing how template
compatibility is tracked solely by immutable versions; make the change near the
community-contributed templates list and in the [[deprecation-policy]] section
so both reference the same authoritative approach to spec_compatibility and
compatibility declarations.
- Around line 195-215: The example link in the "3. Validator Messages" section
of VERSIONING.adoc points to a placeholder URL that 404s; update the example
line that currently reads "See CHANGELOG for what changed:
https://github.com/bigbio/.../CHANGELOG.md" to a working URL or a relative link
to the project's CHANGELOG.md (e.g., "See CHANGELOG for what changed:
../CHANGELOG.md" or the repository's actual CHANGELOG URL) so the CI link
checker no longer fails; locate the exact text in the "Validator Messages"
paragraph and replace only the placeholder URL.
| Community-contributed templates MUST: | ||
|
|
||
| 1. Be submitted as a pull request to the https://github.com/bigbio/sdrf-templates[sdrf-templates] repository. The PR must include the YAML schema, an example `.sdrf.tsv` file, and documentation (a `README.adoc` in the corresponding `templates/` directory). | ||
| 2. Extend an official template using the `extends` field. | ||
| 3. Follow the same YAML schema structure defined in the link:metadata-guidelines/template-definitions.adoc[Template Definitions Guide]. | ||
| 4. Use the `-dev` suffix for pre-release versions (e.g., `1.0.0-dev`) until the template has been reviewed and accepted by the core team. | ||
| 5. Declare their `spec_compatibility` range (see <<deprecation-policy>>). | ||
|
|
||
| Once merged, community templates become part of the official template catalog and appear in the `templates.yaml` manifest. The original contributors are expected to help maintain the template, but the core team assumes responsibility for ensuring compatibility with future specification releases. | ||
|
|
||
| IMPORTANT: The validator only recognizes templates present in the official `sdrf-templates` repository. Using `comment[sdrf template]` to reference a template name that does not exist in the catalog will produce a validation warning. | ||
|
|
||
| When a base template is updated, community template maintainers are responsible for testing compatibility and releasing updated versions via pull request. The validator SHOULD emit a warning when a community template references a base template version older than the latest available. | ||
|
|
||
| [[deprecation-policy]] | ||
| == Deprecation Policy | ||
|
|
||
| === Core Principle: Versions Are Immutable | ||
|
|
||
| Once a template version is released (e.g., `human/1.1.0/human.yaml`), it is never modified or deleted. Changes go into a **new version** (e.g., `human/1.2.0/human.yaml`). This means: | ||
|
|
||
| * An SDRF file that was valid under `human v1.1.0` will always be valid under `human v1.1.0`. | ||
| * The validator loads whichever template version the file declares. | ||
| * No special deprecation metadata is added to template YAML files — each version is its own complete, self-contained truth. | ||
|
|
||
| There is no `deprecated:` flag, no `spec_compatibility:` range, and no deprecation schedule file. The mechanism is simply: **old versions stay, new versions are added, and the validator picks the right one.** | ||
|
|
There was a problem hiding this comment.
Resolve the spec_compatibility contradiction.
This section requires community templates to declare spec_compatibility, but the deprecation policy later states there is no spec_compatibility range. Please align the policy text so it’s unambiguous.
🤖 Prompt for AI Agents
In `@sdrf-proteomics/VERSIONING.adoc` around lines 138 - 164, The text is
contradictory: the community template rules require a spec_compatibility
declaration (spec_compatibility) but the deprecation policy section claims there
is no spec_compatibility metadata; update the document to be consistent by
either (A) keeping the community rule and removing the sentence "There is no
`deprecated:` flag, no `spec_compatibility:` range..." (or rewording it to say
spec_compatibility is required for community templates only), or (B) removing
the community-rule requirement for `spec_compatibility` and instead describing
how template compatibility is tracked solely by immutable versions; make the
change near the community-contributed templates list and in the
[[deprecation-policy]] section so both reference the same authoritative approach
to spec_compatibility and compatibility declarations.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@sdrf-proteomics/VERSIONING.adoc`:
- Line 107: The documentation contains a broken cross-reference to
link:open-issues.adoc; locate the reference (the `link:open-issues.adoc` token)
in VERSIONING.adoc and either add a new open-issues.adoc documenting the
intended content or replace/remove the `link:open-issues.adoc` reference with a
valid target (for example another existing page such as
metadata-guidelines/template-definitions.adoc or an appropriate anchor like
<<versioning>>), ensuring the replacement preserves the intended context and
renders without a broken link.
… original sdrf-templates repo
fix link to template
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@sdrf-proteomics/templates/immunopeptidomics/README.adoc`:
- Around line 287-289: The README.adoc uses a hard-coded dev path
immunopeptidomics/1.0.0-dev/immunopeptidomics.sdrf.tsv which will become a dead
link when the template is published; update the link in
immunopeptidomics/README.adoc to a stable permalink (either the released tag
e.g., immunopeptidomics/1.0.0/ path or a blob URL pinned to a specific commit
SHA) or point to the repository’s stable release page for the template, and
replace any references to the mutable master/dev branch with that stable URL or
add a short note explaining the link points to the development branch and may
change.
In `@sdrf-proteomics/templates/metaproteomics/README.adoc`:
- Around line 508-510: Update the README link that currently points to
metaproteomics/1.0.0-dev/metaproteomics.sdrf.tsv so it uses
metaproteomics/1.0.0/metaproteomics.sdrf.tsv when the template reaches stable
release; locate the string
"link:https://github.com/bigbio/sdrf-templates/blob/master/metaproteomics/1.0.0-dev/metaproteomics.sdrf.tsv[metaproteomics.sdrf.tsv]"
in templates/metaproteomics/README.adoc and replace the "-dev" segment with the
stable "1.0.0" directory (or coordinate with the template maintainers to update
the URL in sync with the release), and ensure any other occurrences of
"metaproteomics/1.0.0-dev" are similarly updated or made configurable to avoid
future 404s.
In `@sdrf-proteomics/templates/somascan/README.adoc`:
- Around line 321-323: Update the hardcoded GitHub link
'https://github.com/bigbio/sdrf-templates/blob/master/somascan/1.0.0/somascan.sdrf.tsv'
in the README.adoc to point to a stable reference instead of the mutable
'master' branch; replace the 'blob/master/...' segment with either a release tag
(e.g., 'blob/v1.0.0/somascan/1.0.0/somascan.sdrf.tsv') if the repo has a
matching tag or a permanent commit SHA (e.g.,
'blob/<commit-hash>/somascan/1.0.0/somascan.sdrf.tsv') to ensure the link
remains valid.
In `@sdrf-proteomics/VERSIONING.adoc`:
- Around line 498-500: The summary row titled "Machine-readable schedules"
contradicts the Deprecation Policy; update the text in VERSIONING.adoc to stop
implying a separate deprecation schedule YAML exists—either remove that summary
row or reword it to state that the repository provides machine-readable template
discovery/version-catalog information (e.g., reference "templates.yaml"
manifest) rather than a deprecation schedule; ensure the new wording replaces
the phrase "deprecation schedule and template compatibility information" with
something like "template discovery and version compatibility manifest
(machine-readable YAML)" so it aligns with the Deprecation Policy and the actual
role of templates.yaml.
- Around line 95-99: The TSV example in VERSIONING.adoc uses a duplicated header
name "comment[sdrf template]" which is invalid; update the header to use a
single "comment[sdrf template]" column and represent multiple templates as a
single cell (e.g., comma- or space-separated list) or adopt disambiguated
indexed headers (e.g., "comment[sdrf template]1", "comment[sdrf template]2"),
and adjust the data row ("v1.1.0 human v1.1.0 ms-proteomics v1.1.0") to match
the chosen approach so the header and row align (update the example under the
[source,tsv] block accordingly).
---
Duplicate comments:
In `@sdrf-proteomics/templates/base/README.adoc`:
- Around line 31-32: The links in templates/base/README.adoc point to the
repository via the mutable "master" branch; update both URLs (the links
referencing base.yaml and base.sdrf.tsv) to use an immutable reference (e.g.,
the release tag or specific commit SHA such as replacing "blob/master" with
"blob/1.1.0" or the chosen stable tag/commit) so the template references remain
stable over time.
In `@sdrf-proteomics/templates/cell-lines/README.adoc`:
- Around line 585-587: The README currently links to the SDRF template using the
mutable master branch; update the link in
sdrf-proteomics/templates/cell-lines/README.adoc so it references an immutable
tag or commit for the 1.1.0 template (e.g., replace the master-based URL with
the repository URL that includes the release tag or a specific commit SHA for
cell-lines/1.1.0/cell-lines.sdrf.tsv), ensuring the link points to a stable
version rather than master.
In `@sdrf-proteomics/templates/dda-acquisition/README.adoc`:
- Around line 357-359: The README currently links to the file in the
sdrf-templates repo using the repository's default (mutable) branch; update the
link in sdrf-proteomics/templates/dda-acquisition/README.adoc so it points to an
immutable reference (a release tag or specific commit) instead of the master
branch—replace the current URL that ends with
/blob/master/.../dda-acquisition/1.1.0/dda-acquisition.sdrf.tsv with a URL that
uses a tag or commit hash (e.g., /blob/v1.1.0/... or /blob/<commit-hash>/...) so
the referenced dda-acquisition.sdrf.tsv cannot change unexpectedly.
In `@sdrf-proteomics/templates/olink/README.adoc`:
- Around line 290-292: The README currently links to the olink.sdrf.tsv on the
repository's mutable master branch; change the link to point to an immutable
reference (a release tag or commit SHA) for the Olink template so it can't
change unexpectedly—update the link target that references "olink.sdrf.tsv" to
use the repository tag (e.g., /blob/v1.0.0/olink/1.0.0/olink.sdrf.tsv) or a
specific commit hash instead of master.
In `@sdrf-proteomics/templates/single-cell/README.adoc`:
- Around line 554-556: The README currently links to the single-cell.sdrf.tsv on
the mutable master branch; update the link (the URL containing
"bigbio/sdrf-templates/.../single-cell.sdrf.tsv" referenced in README.adoc) to
point to an immutable reference — either a specific release/tag (e.g.
/releases/tag/vX.Y.Z) or a commit SHA or the stable "main" tree path — so the
template reference won't break when upstream moves; adjust the link text if
needed to reflect the chosen immutable reference.
In `@sdrf-proteomics/VERSIONING.adoc`:
- Line 507: VERSIONING.adoc contains a broken reference
"link:open-issues.adoc[Open Issues and Future Decisions]" because
open-issues.adoc is missing; fix by either adding the missing open-issues.adoc
file with the intended content or replacing the link in VERSIONING.adoc with a
valid target (for example a GitHub issues filter URL or removing the entry) so
the "link:open-issues.adoc[Open Issues and Future Decisions]" reference resolves
correctly.
- Around line 138-145: The doc contains a contradiction between the community
template requirements (bullet requiring a declared spec_compatibility range via
the `spec_compatibility` field) and the Deprecation Policy sentence stating
“There is no `spec_compatibility:` range”; fix by choosing one of two edits: (A)
remove bullet 5 requiring `spec_compatibility` from the community template list
(and keep the Deprecation Policy as-is), or (B) define `spec_compatibility` in
the template YAML schema (Template Definitions Guide) and delete or reword the
Deprecation Policy sentence that says there is no `spec_compatibility:` range so
both docs consistently require and describe the `spec_compatibility` field;
update mentions of `spec_compatibility` and the Deprecation Policy paragraph to
be consistent.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the SDRF-Proteomics documentation to centralize template artifacts in the sdrf-templates repository, introduces a dedicated versioning/deprecation policy document, and adds an llms.txt index file intended for LLM-oriented navigation of the repo’s docs and assets.
Changes:
- Point multiple template READMEs to versioned template files in the
sdrf-templatesrepository. - Add
sdrf-proteomics/VERSIONING.adocand link it from the main SDRF-Proteomics README. - Expand the “creating templates” guidance and remove now-unreferenced internal resources (LinkML schema + enzymes TSV).
Reviewed changes
Copilot reviewed 17 out of 18 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| sdrf-proteomics/templates/somascan/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/templates/single-cell/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/templates/olink/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/templates/metaproteomics/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/templates/immunopeptidomics/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/templates/dia-acquisition/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/templates/dda-acquisition/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/templates/cell-lines/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/templates/base/README.adoc | Switches to direct links for base template artifacts in sdrf-templates. |
| sdrf-proteomics/templates/affinity-proteomics/README.adoc | Updates template file link to sdrf-templates repo. |
| sdrf-proteomics/metadata-guidelines/template-definitions.adoc | Replaces prior “LinkML schema” section with step-by-step template creation guide + examples. |
| sdrf-proteomics/templates/sdrf-template-schema.linkml.yaml | Removes the internal LinkML schema file. |
| sdrf-proteomics/metadata-guidelines/enzymes.tsv | Removes an enzymes TSV resource. |
| sdrf-proteomics/VERSIONING.adoc | Adds a comprehensive versioning/deprecation policy document. |
| sdrf-proteomics/README.adoc | Links to the new versioning/deprecation policy doc. |
| llms.txt | Adds an LLM-oriented repository index file. |
| README.md | Adds an llms.txt availability badge. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 2. Extend an official template using the `extends` field. | ||
| 3. Follow the same YAML schema structure defined in the link:metadata-guidelines/template-definitions.adoc[Template Definitions Guide]. | ||
| 4. Use the `-dev` suffix for pre-release versions (e.g., `1.0.0-dev`) until the template has been reviewed and accepted by the core team. | ||
| 5. Declare their `spec_compatibility` range (see <<deprecation-policy>>). |
There was a problem hiding this comment.
This list requires community templates to declare a spec_compatibility range, but the Deprecation Policy later states there is no spec_compatibility field (and no extra deprecation metadata). These statements conflict; please either define spec_compatibility and how it is used, or remove this requirement so the policy is self-consistent.
| 5. Declare their `spec_compatibility` range (see <<deprecation-policy>>). |
|
|
||
| ==== 1. GitHub Issues (before the change) | ||
|
|
||
| Every change that affects existing SDRF files starts as a **GitHub issue** in the https://github.com/bigbio/proteomics-sample-metadata[specification repository]. The issue describes the proposal, the rationale, and the impact. Community members comment and vote. No change is merged without community input. |
There was a problem hiding this comment.
This section calls bigbio/proteomics-sample-metadata the “specification repository”, but this document lives in bigbio/proteomics-metadata-standard (and the root README/issue links point here). Please update the repository link (and related links below, like the CHANGELOG/issue reference) or explicitly explain why versioning issues are tracked in a different repo.
| Every change that affects existing SDRF files starts as a **GitHub issue** in the https://github.com/bigbio/proteomics-sample-metadata[specification repository]. The issue describes the proposal, the rationale, and the impact. Community members comment and vote. No change is merged without community input. | |
| Every change that affects existing SDRF files starts as a **GitHub issue** in the https://github.com/bigbio/proteomics-metadata-standard[specification repository]. The issue describes the proposal, the rationale, and the impact. Community members comment and vote. No change is merged without community input. |
| ---- | ||
| INFO: Template 'human v1.2.0' is available. | ||
| Your file uses 'human v1.1.0' and is valid under that version. | ||
| See CHANGELOG for what changed: https://github.com/bigbio/proteomics-sample-metadata/blob/master/CHANGELOG.md |
There was a problem hiding this comment.
The example validator message links to https://github.com/bigbio/proteomics-sample-metadata/blob/master/CHANGELOG.md, but this repository already contains CHANGELOG.md. Consider linking to the local changelog (or the correct canonical repo) so the pointer doesn’t break or diverge from the actual release notes for this codebase.
| See CHANGELOG for what changed: https://github.com/bigbio/proteomics-sample-metadata/blob/master/CHANGELOG.md | |
| See CHANGELOG for what changed: CHANGELOG.md |
| Key points demonstrated in this example: | ||
|
|
||
| For tools requiring a formal schema language, a https://linkml.io/[LinkML] representation is available: | ||
| * **New columns** (`comment[protein separation method]`, `comment[precursor mass range]`) are defined with their own validators. | ||
| * **Overriding an inherited column** (`comment[cleavage agent details]`) restricts the parent's definition — in this case, forcing the value to "not applicable" since top-down experiments don't use enzymatic digestion. | ||
| * **Descriptions explain the "why"** — not just what the field is, but when to use `not applicable` and what format to follow. | ||
| * **Examples are always provided** in validators — they serve as documentation and can be used by tools to generate autocomplete suggestions. |
There was a problem hiding this comment.
This PR deletes sdrf-proteomics/templates/sdrf-template-schema.linkml.yaml, but the repository still contains references to that file (e.g., psi-document/v1.1.0-dev/supplementary-files/template-definitions-v1.1.0-dev.adoc). Please update/remove those references or keep a replacement/redirect, otherwise the docs will contain broken links.
change blob/master to tree/main for correct branch reference of template file and add template-file section header to various .adoc before template link to ensure consistency between templates adoc. fix inconsistency in repo name in repo name badgen link and sample template hyperlink.
…ge, RT, and IM using PRIDE ontology terms
Fix hyperlink inconsistency
Add optional precursor mass/charge/RT/IM range columns to DDA/DIA template
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (2)
.gitignore (1)
81-81: Consider anchoring the pattern to the repository root if only the root-level file should be ignored.The unanchored
CLAUDE.mdpattern matches any file with that name at any depth in the repository. If Claude Code can also createCLAUDE.mdfiles in subdirectories (which it does for nested project contexts), this is intentional and fine. If only the root-level file should be ignored, use/CLAUDE.md.🔧 Proposed change (if root-only intent)
-CLAUDE.md +/CLAUDE.md🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.gitignore at line 81, The .gitignore currently uses an unanchored pattern "CLAUDE.md" which ignores that filename at any depth; if the intent is to ignore only the repository root file, change the pattern to "/CLAUDE.md" so it is anchored to the root; if you do intend to ignore all occurrences (including nested CLAUDE.md files), leave the pattern as-is—look for the "CLAUDE.md" entry in .gitignore to apply this change.sdrf-proteomics/templates/human/README.adoc (1)
1658-1664:Template Filesection placement is inconsistent with other templatesIn all other updated templates (cell-lines, vertebrates, plants, invertebrates, ms-proteomics), the "Template File" section appears near the end of the document but before the Validation and/or Examples sections. In this file it is appended after the References section, making it the last section in the document. For discoverability and consistency, consider moving it to sit before the
[[validation]]section (Line 198) or at minimum before== References(Line 1635).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@sdrf-proteomics/templates/human/README.adoc` around lines 1658 - 1664, The "Template File" section ([[template-file]] / "== Template File") is placed after "== References" making it the last section; move this entire section so it appears before the validation block (marker [[validation]]) or at minimum before the "== References" header to match other templates' structure; locate the "== Template File" block in sdrf-proteomics/templates/human/README.adoc and cut/paste it to immediately precede the [[validation]] section (or just above "== References") so ordering is consistent with other templates.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@sdrf-proteomics/templates/cell-lines/README.adoc`:
- Around line 585-587: The README.adoc references an immunopeptidomics template
link that returns 404; verify whether the file exists in the sdrf-templates repo
and either update the URL to the correct path or remove/replace the broken link
entry. In sdrf-proteomics/templates/cell-lines/README.adoc, locate the link
block (the existing cell-lines.sdrf.tsv link) and add or replace a correct link
for immunopeptidomics (or a note that the template is unavailable), making sure
the URL matches the actual path in bigbio/sdrf-templates (or points to the
correct tag/version).
In `@sdrf-proteomics/templates/crosslinking/README.adoc`:
- Around line 496-502: Update the document's version strings from "1.0.0" to
"1.1.0": replace the "Version: 1.0.0" declaration and any example references
like "crosslinking v1.0.0" with "1.1.0" so they match the linked template
(referenced by the crosslinking.sdrf.tsv link and the "Version: 1.0.0" and
"crosslinking v1.0.0" occurrences).
In `@sdrf-proteomics/VERSIONING.adoc`:
- Around line 484-485: The summary row titled "No surprise breakage" overstates
the deprecation window by blanket-stating "user-facing breaking changes require
at least 2 MINOR releases (12 months)"; update that row to explicitly
differentiate the two tiers from Section 5.2 (Feature Lifecycle Policy) by
stating that Display Features require 2 MINOR releases (12 months) while
Background Features require 1 MINOR release (6 months), and either replace or
define the ambiguous term "user-facing" to map to "Display Features" (or remove
it) so the summary aligns with the Background Feature and Display Feature rules.
- Around line 379-392: Add a clear NOTE/IMPORTANT admonition at the top of the
Validator Behavior section stating that the CLI flags --spec-version,
--use-declared-version, --strict, --legacy, --ontology-date and the command
parse_sdrf migrate are not implemented in the current sdrf-pipelines release
(v0.1.0) and are planned/future features; list the only supported flags
(--sdrf_file, --template, --skip-ontology, --use_ols_cache_only and
proof-related options), and instruct readers to upgrade when those features are
released or consult the project changelog for availability to avoid running into
errors.
---
Duplicate comments:
In `@sdrf-proteomics/templates/immunopeptidomics/README.adoc`:
- Around line 287-289: The README.adoc currently hard-codes the unstable path
"immunopeptidomics/1.0.0-dev/immunopeptidomics.sdrf.tsv" which will become a
dead link once the template is published; update the reference in
sdrf-proteomics/templates/immunopeptidomics/README.adoc to point to a stable
location (for example the repository root or the releases/tags page) or change
the path to the stable release directory (e.g., replace
"immunopeptidomics/1.0.0-dev/" with "immunopeptidomics/1.1.0/" or a
variable/anchor) and add a short note indicating the link targets the
development branch if you keep the dev path; search for the literal string
"immunopeptidomics/1.0.0-dev/immunopeptidomics.sdrf.tsv" to locate the line to
change.
In `@sdrf-proteomics/VERSIONING.adoc`:
- Around line 95-99: The TSV example header contains a duplicated column name
"comment[sdrf template]" which is invalid; update the header in the [source,tsv]
block so "comment[sdrf template]" appears only once and adjust the corresponding
data row (the line with v1.1.0 human v1.1.0 ms-proteomics v1.1.0) to have one
fewer column entry so columns align correctly; search for the header string
"comment[sdrf template]" to locate and fix the duplicate.
- Around line 138-202: There is a contradiction between the Community Templates
requirement (list item 5 under "Community-contributed templates MUST" that says
"Declare their `spec_compatibility` range") and the Deprecation Policy paragraph
that states "There is no `deprecated:` flag, no `spec_compatibility:` range";
either remove the `spec_compatibility` requirement from the community-template
MUST list or update the Deprecation Policy text to explicitly allow a
community-template-only `spec_compatibility` field (e.g., add a sentence after
"There is no `deprecated:` flag..." stating that community templates MAY declare
`spec_compatibility` and describe its intended semantics); update the wording
consistently so the two places no longer contradict each other and keep the
referenced phrases ("Declare their `spec_compatibility` range" and "There is no
`deprecated:` flag, no `spec_compatibility:` range") in sync.
---
Nitpick comments:
In @.gitignore:
- Line 81: The .gitignore currently uses an unanchored pattern "CLAUDE.md" which
ignores that filename at any depth; if the intent is to ignore only the
repository root file, change the pattern to "/CLAUDE.md" so it is anchored to
the root; if you do intend to ignore all occurrences (including nested CLAUDE.md
files), leave the pattern as-is—look for the "CLAUDE.md" entry in .gitignore to
apply this change.
In `@sdrf-proteomics/templates/human/README.adoc`:
- Around line 1658-1664: The "Template File" section ([[template-file]] / "==
Template File") is placed after "== References" making it the last section; move
this entire section so it appears before the validation block (marker
[[validation]]) or at minimum before the "== References" header to match other
templates' structure; locate the "== Template File" block in
sdrf-proteomics/templates/human/README.adoc and cut/paste it to immediately
precede the [[validation]] section (or just above "== References") so ordering
is consistent with other templates.
| The cell line SDRF template file is available in the sdrf-templates repository: | ||
|
|
||
| - link:cell-lines-template.sdrf.tsv[cell-lines-template.sdrf.tsv] | ||
| - link:https://github.com/bigbio/sdrf-templates/blob/main/cell-lines/1.1.0/cell-lines.sdrf.tsv[cell-lines.sdrf.tsv] |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check whether bigbio/sdrf-templates exists and whether the
# key template files are reachable.
echo "=== Checking repository existence ==="
repo_code=$(curl -s -o /dev/null -w "%{http_code}" \
"https://api.github.com/repos/bigbio/sdrf-templates")
echo "Repository API response code: ${repo_code}"
echo ""
echo "=== Spot-checking template file paths ==="
# Spot-check a few template file paths
for path in \
"cell-lines/1.1.0/cell-lines.sdrf.tsv" \
"human/1.1.0/human.sdrf.tsv" \
"ms-proteomics/1.1.0/ms-proteomics.sdrf.tsv" \
"immunopeptidomics/1.0.0-dev/immunopeptidomics.sdrf.tsv"; do
code=$(curl -s -o /dev/null -w "%{http_code}" \
"https://github.com/bigbio/sdrf-templates/blob/main/${path}")
echo "${path}: HTTP ${code}"
doneRepository: bigbio/proteomics-sample-metadata
Length of output: 393
Address unreachable immunopeptidomics template path
The bigbio/sdrf-templates repository exists and is publicly accessible. However, the immunopeptidomics template file at https://github.com/bigbio/sdrf-templates/blob/main/immunopeptidomics/1.0.0-dev/immunopeptidomics.sdrf.tsv returns HTTP 404. Verify whether this file exists in the repository or update the link to point to the correct path.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@sdrf-proteomics/templates/cell-lines/README.adoc` around lines 585 - 587, The
README.adoc references an immunopeptidomics template link that returns 404;
verify whether the file exists in the sdrf-templates repo and either update the
URL to the correct path or remove/replace the broken link entry. In
sdrf-proteomics/templates/cell-lines/README.adoc, locate the link block (the
existing cell-lines.sdrf.tsv link) and add or replace a correct link for
immunopeptidomics (or a note that the template is unavailable), making sure the
URL matches the actual path in bigbio/sdrf-templates (or points to the correct
tag/version).
| [[template-file]] | ||
| == Template File | ||
|
|
||
| The crosslinking SDRF template file is available in the sdrf-templates repository: | ||
|
|
||
| - link:https://github.com/bigbio/sdrf-templates/blob/main/crosslinking/1.1.0/crosslinking.sdrf.tsv[crosslinking.sdrf.tsv] | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let me examine the file to confirm the stated facts
cat -n sdrf-proteomics/templates/crosslinking/README.adoc | sed -n '25,35p'Repository: bigbio/proteomics-sample-metadata
Length of output: 592
🏁 Script executed:
# Check lines around 116 and 124 for the template version references
cat -n sdrf-proteomics/templates/crosslinking/README.adoc | sed -n '110,130p'Repository: bigbio/proteomics-sample-metadata
Length of output: 739
🏁 Script executed:
# Check the newly added section around line 496-502
cat -n sdrf-proteomics/templates/crosslinking/README.adoc | sed -n '495,510p'Repository: bigbio/proteomics-sample-metadata
Length of output: 1080
🌐 Web query:
bigbio sdrf-templates github repository
💡 Result:
The BIGBIO SDRF templates live in the bigbio/proteomics-sample-metadata GitHub repository (see the templates/ and sdrf-proteomics/ directories). [1]
https://github.com/bigbio/proteomics-sample-metadata
https://github.com/bigbio/proteomics-sample-metadata/tree/master/templates
https://github.com/bigbio/proteomics-sample-metadata/tree/master/sdrf-proteomics
Sources: [1]
🏁 Script executed:
# Check if there's a crosslinking template path in the correct repository
# Look for crosslinking files in proteomics-sample-metadata
curl -s "https://api.github.com/repos/bigbio/proteomics-sample-metadata/contents/sdrf-proteomics/templates/crosslinking" | jq -r '.[] | select(.name | contains("sdrf")) | .name' | head -20Repository: bigbio/proteomics-sample-metadata
Length of output: 59
🏁 Script executed:
# Also check the GitHub raw content to see what versions exist
curl -s "https://api.github.com/repos/bigbio/proteomics-sample-metadata/contents/sdrf-proteomics/templates" | jq -r '.[] | select(.type=="dir") | .name'Repository: bigbio/proteomics-sample-metadata
Length of output: 141
🏁 Script executed:
# Test the actual URL from the document to see if it resolves
curl -I -s "https://github.com/bigbio/sdrf-templates/blob/main/crosslinking/1.1.0/crosslinking.sdrf.tsv" | head -1
# Test what the correct repo path should be (with proteomics-sample-metadata)
curl -I -s "https://github.com/bigbio/proteomics-sample-metadata/blob/main/sdrf-proteomics/templates/crosslinking/1.0.0/crosslinking.sdrf.tsv" | head -1Repository: bigbio/proteomics-sample-metadata
Length of output: 101
🏁 Script executed:
# Try to find the actual crosslinking template files in the correct repository
# by browsing the directory structure
curl -s "https://api.github.com/repos/bigbio/proteomics-sample-metadata/contents/sdrf-proteomics/templates/crosslinking" 2>/dev/null | grep -o '"name":"[^"]*"' | head -20Repository: bigbio/proteomics-sample-metadata
Length of output: 59
🏁 Script executed:
# Test the 1.0.0 version path in the sdrf-templates repo (the one the document should link to if version is 1.0.0)
curl -I -s "https://github.com/bigbio/sdrf-templates/blob/main/crosslinking/1.0.0/crosslinking.sdrf.tsv" | head -1
# Also test with raw content to be thorough
curl -I -s "https://raw.githubusercontent.com/bigbio/sdrf-templates/main/crosslinking/1.0.0/crosslinking.sdrf.tsv" | head -1
curl -I -s "https://raw.githubusercontent.com/bigbio/sdrf-templates/main/crosslinking/1.1.0/crosslinking.sdrf.tsv" | head -1Repository: bigbio/proteomics-sample-metadata
Length of output: 114
🏁 Script executed:
# Confirm the 1.1.0 version path truly exists by checking for actual file content
curl -s "https://raw.githubusercontent.com/bigbio/sdrf-templates/main/crosslinking/1.1.0/crosslinking.sdrf.tsv" | head -5Repository: bigbio/proteomics-sample-metadata
Length of output: 937
Version declarations should be updated to 1.1.0 to match the linked template.
The document declares Version: 1.0.0 at line 30, with examples at lines 116 and 124 also referencing crosslinking v1.0.0. However, the linked template file at line 501 points to the 1.1.0 version. Testing confirms that the 1.1.0 path exists and is correct, while the 1.0.0 path does not exist in the repository. Update the version declarations at lines 30, 116, and 124 from 1.0.0 to 1.1.0 to align with the actual available template.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@sdrf-proteomics/templates/crosslinking/README.adoc` around lines 496 - 502,
Update the document's version strings from "1.0.0" to "1.1.0": replace the
"Version: 1.0.0" declaration and any example references like "crosslinking
v1.0.0" with "1.1.0" so they match the linked template (referenced by the
crosslinking.sdrf.tsv link and the "Version: 1.0.0" and "crosslinking v1.0.0"
occurrences).
| [source,bash] | ||
| ---- | ||
| # Validate against a specific specification version | ||
| parse_sdrf validate-sdrf --sdrf_file data.sdrf.tsv --spec-version v1.1.0 | ||
|
|
||
| # Validate using the version declared in the file (comment[sdrf version]) | ||
| parse_sdrf validate-sdrf --sdrf_file data.sdrf.tsv --use-declared-version | ||
|
|
||
| # Validate with strict mode (reject all deprecated features) | ||
| parse_sdrf validate-sdrf --sdrf_file data.sdrf.tsv --strict | ||
|
|
||
| # Validate with legacy mode (accept removed features from previous major version) | ||
| parse_sdrf validate-sdrf --sdrf_file data.sdrf.tsv --legacy v1.0.0 | ||
| ---- |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, explore the repository structure
find . -type f -name "VERSIONING.adoc" | head -5Repository: bigbio/proteomics-sample-metadata
Length of output: 110
🏁 Script executed:
# Look for sdrf-pipelines references and validate-sdrf implementation
find . -type f -name "*validate*" -o -name "*sdrf_pipelines*" | head -20Repository: bigbio/proteomics-sample-metadata
Length of output: 113
🏁 Script executed:
# Search for validate-sdrf command implementation in Python files
rg -l "validate.sdrf|validate_sdrf" --type py | head -10Repository: bigbio/proteomics-sample-metadata
Length of output: 59
🏁 Script executed:
# Check the VERSIONING.adoc file content around the mentioned lines
if [ -f "sdrf-proteomics/VERSIONING.adoc" ]; then
wc -l sdrf-proteomics/VERSIONING.adoc
sed -n '370,400p' sdrf-proteomics/VERSIONING.adoc
echo "---Lines around 298---"
sed -n '295,305p' sdrf-proteomics/VERSIONING.adoc
echo "---Lines around 473---"
sed -n '470,480p' sdrf-proteomics/VERSIONING.adoc
fiRepository: bigbio/proteomics-sample-metadata
Length of output: 2324
🏁 Script executed:
# Search for any documentation or implementation of parse_sdrf migrate
rg "migrate" --type py -A 2 -B 2 | head -50Repository: bigbio/proteomics-sample-metadata
Length of output: 59
🏁 Script executed:
# Search more broadly for validate-sdrf or validation implementations
rg "validate.sdrf|validate-sdrf" --type py -iRepository: bigbio/proteomics-sample-metadata
Length of output: 59
🏁 Script executed:
# Look for sdrf-pipelines references in config files
rg "sdrf-pipelines|sdrf_pipelines" --type yml --type yaml --type toml --type txtRepository: bigbio/proteomics-sample-metadata
Length of output: 104
🏁 Script executed:
# Check if there's a setup.py or pyproject.toml that lists dependencies
find . -name "setup.py" -o -name "pyproject.toml" -o -name "requirements*.txt" | xargs cat 2>/dev/null | grep -A 5 -B 5 "sdrf"Repository: bigbio/proteomics-sample-metadata
Length of output: 59
🏁 Script executed:
# Look for any CLI command definitions or argument parsers
rg "click|argparse|@click" --type py -l | head -10Repository: bigbio/proteomics-sample-metadata
Length of output: 59
🏁 Script executed:
# Check the README or documentation for validation examples
cat sdrf-proteomics/README.adoc 2>/dev/null | head -200Repository: bigbio/proteomics-sample-metadata
Length of output: 11947
🌐 Web query:
sdrf-pipelines validate-sdrf flags implementation GitHub
💡 Result:
parse_sdrf validate-sdrf is implemented as a click subcommand in src/sdrf_pipelines/parse_sdrf.py (function validate_sdrf) and its flags are defined via @click.option(...) decorators. [2]
Flags (as implemented)
-s, --sdrf_file TEXT: SDRF file path to validate. [1][2]-t, --template TEXT: Template name to validate against (defaults todefault). [1][2]--use_ols_cache_only: Validate ontology terms using the local OLS cache only (no network OLS calls). [1][2]--skip-ontology: Skip ontology term validation entirely. [1][2]-o, --out TEXT: Write validation results table to a TSV file (otherwise prints to stdout). [1][2]-po, --proof_out TEXT: Write a validation proof JSON to a file. [1][2]--generate_proof: Generate and print a cryptographic validation proof (or write it if--proof_outis set). [1][2]--proof_salt TEXT: Optional user-provided salt used in proof generation. [1][2]
Notable behavior tied to flags
- If
--skip-ontologyis not set but ontology dependencies are missing, the command prints a warning and forcibly switches to structural-only validation by settingskip_ontology = True. [2] - Exit code is non-zero if there are errors (warnings-only still exits 0). This is done via
sys.exit(bool(errors_not_warnings)). [2]
Sources: auto-generated CLI docs (COMMANDS.md) [1] and the actual click command implementation (parse_sdrf.py) [2].
🌐 Web query:
sdrf-pipelines PyPI documentation spec-version use-declared-version
💡 Result:
In the current sdrf-pipelines docs/CLI (PyPI release 0.1.0, Feb 4, 2026), I can’t find any documented flags or configuration keys named spec-version or use-declared-version. The auto-generated CLI reference (COMMANDS.md) and the CLI implementation (parse_sdrf.py) don’t mention them. [1] [2]
What is implemented today is template version selection inside the schema loader:
- Templates are loaded from a versioned directory layout:
{template_name}/{version}/{template_name}.yaml, and atemplates.yamlmanifest (if present) is used to pick thelatestversion for each template. [3] - If a template isn’t listed in the manifest, the code falls back to choosing the last version directory by sorting directory names. [3]
So, if you saw spec-version / use-declared-version, they’re likely from different tooling, an older/experimental doc, or a template-manifest/spec proposal that isn’t in the current published CLI/docs.
References
[1] sdrf-pipelines PyPI page (mentions CLI docs / usage): https://pypi.org/project/sdrf-pipelines/ (pypi.org)
[2] parse_sdrf CLI implementation (no spec-version / use-declared-version): https://raw.githubusercontent.com/bigbio/sdrf-pipelines/main/src/sdrf_pipelines/parse_sdrf.py (raw.githubusercontent.com)
[3] SchemaRegistry template versioning + templates.yaml “latest” logic: https://raw.githubusercontent.com/bigbio/sdrf-pipelines/main/src/sdrf_pipelines/sdrf/schemas/registry.py (raw.githubusercontent.com)
Citations:
- 1: https://pypi.org/project/sdrf-pipelines/
- 2: https://raw.githubusercontent.com/bigbio/sdrf-pipelines/main/src/sdrf_pipelines/parse_sdrf.py
- 3: https://raw.githubusercontent.com/bigbio/sdrf-pipelines/main/src/sdrf_pipelines/sdrf/schemas/registry.py
Undocumented flags and parse_sdrf migrate command create a specification-implementation gap.
The section uses RFC 2119 "MUST support" language and presents CLI syntax for --spec-version, --use-declared-version, --strict, and --legacy (lines 379–392), plus --ontology-date (line 371) and parse_sdrf migrate (lines 298, 473). None of these are implemented in the current sdrf-pipelines release (v0.1.0, Feb 2026); the only supported flags are --sdrf_file, --template, --skip-ontology, --use_ols_cache_only, and proof-related options.
Downstream consumers reading this section without a clear "future requirement" marker will attempt to run these commands against the current tooling and receive errors. Add a NOTE or IMPORTANT admonition at the top of the Validator Behavior section to clarify implementation status:
Suggested addition to VERSIONING.adoc
== Validator Behavior
+NOTE: The commands and flags in this section define *requirements* for future sdrf-pipelines releases. Not all flags and commands described here are implemented in the current release. Check https://github.com/bigbio/sdrf-pipelines[sdrf-pipelines] for the currently available features.
+
=== Version-Aware Validation🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@sdrf-proteomics/VERSIONING.adoc` around lines 379 - 392, Add a clear
NOTE/IMPORTANT admonition at the top of the Validator Behavior section stating
that the CLI flags --spec-version, --use-declared-version, --strict, --legacy,
--ontology-date and the command parse_sdrf migrate are not implemented in the
current sdrf-pipelines release (v0.1.0) and are planned/future features; list
the only supported flags (--sdrf_file, --template, --skip-ontology,
--use_ols_cache_only and proof-related options), and instruct readers to upgrade
when those features are released or consult the project changelog for
availability to avoid running into errors.
| | **No surprise breakage** | ||
| | User-facing breaking changes require at least 2 MINOR releases (12 months minimum) of deprecation warnings before enforcement. |
There was a problem hiding this comment.
Summary guarantee overstates the deprecation window for Background Features.
Line 485 promises that all "user-facing breaking changes require at least 2 MINOR releases (12 months minimum)". However, Section 5.2 (Feature Lifecycle Policy) sets the Background Feature deprecation period at only one Minor version cycle or 6 months (line 184), reserving the two-cycle / 12-month period for Display Features only (line 185). The summary row conflates the two tiers, and the term "user-facing" is never formally defined in the document to mean exclusively "Display Features".
🐛 Suggested fix — differentiate the two tiers in the summary row
| **No surprise breakage**
-| User-facing breaking changes require at least 2 MINOR releases (12 months minimum) of deprecation warnings before enforcement.
+| Breaking changes require a deprecation period before enforcement: at least 1 MINOR release (6 months) for Background Features, and at least 2 MINOR releases (12 months) for Display Features (see <<feature-lifecycle-policy>>).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@sdrf-proteomics/VERSIONING.adoc` around lines 484 - 485, The summary row
titled "No surprise breakage" overstates the deprecation window by
blanket-stating "user-facing breaking changes require at least 2 MINOR releases
(12 months)"; update that row to explicitly differentiate the two tiers from
Section 5.2 (Feature Lifecycle Policy) by stating that Display Features require
2 MINOR releases (12 months) while Background Features require 1 MINOR release
(6 months), and either replace or define the ambiguous term "user-facing" to map
to "Display Features" (or remove it) so the summary aligns with the Background
Feature and Display Feature rules.
Summary by CodeRabbit