VERSIONING and TEMPLATE specifications changed, additionally a file for LLM interations has been created #792
Conversation
Contributor
📝 WalkthroughWalkthroughThis PR adds comprehensive SDRF‑Proteomics documentation and templates (YAML and TSV), includes an llms.txt discovery file and README badge, introduces a VERSIONING.adoc policy, and removes the LinkML template schema file. No code or exported API changes. 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 inconclusive)
✅ 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}
Contributor
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.
|  | ||
|  | ||
|  | ||
| [](https://github.com/bigbio/proteomics-metadata-standard/blob/master/llms.txt) |
Contributor
There was a problem hiding this comment.
Fix llms.txt badge link to the correct repo path (CI link check fails).
The badge currently points to a non-existent path, which is causing the link checker failure. Update it to the correct repository or a relative link.
Suggested fix
-[](https://github.com/bigbio/proteomics-metadata-standard/blob/master/llms.txt)
+[](https://github.com/bigbio/proteomics-sample-metadata/blob/master/llms.txt)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| [](https://github.com/bigbio/proteomics-metadata-standard/blob/master/llms.txt) | |
| [](https://github.com/bigbio/proteomics-sample-metadata/blob/master/llms.txt) |
🤖 Prompt for AI Agents
In `@README.md` at 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.
Comment on lines
138
to
164
| 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.** | ||
|
|
Contributor
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.
Comment on lines
+195
to
+215
| ==== 2. CHANGELOG (at the time of the change) | ||
|
|
||
| When the change is accepted and a new version is released, the `CHANGELOG.md` records: | ||
|
|
||
| * What changed (e.g., "column X moved from required to optional"). | ||
| * Why it changed (link to the GitHub issue). | ||
| * Which template versions are affected (e.g., "human v1.2.0, vertebrates v1.2.0"). | ||
| * What users need to do (e.g., "update your `comment[sdrf template]` to `human v1.2.0`; or keep `human v1.1.0` if you need the old behavior"). | ||
|
|
||
| The CHANGELOG is the permanent human-readable record of all changes. | ||
|
|
||
| ==== 3. Validator Messages (after the change) | ||
|
|
||
| The validator (sdrf-pipelines) is how most users discover that a newer version exists. Each sdrf-pipelines release ships with the full catalog of template versions. When it validates a file, it compares the declared template version to the latest available and reports: | ||
|
|
||
| [source] | ||
| ---- | ||
| 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/.../CHANGELOG.md | ||
| ---- |
Contributor
There was a problem hiding this comment.
Fix CHANGELOG link (CI link check failure).
The example uses a placeholder URL (https://github.com/bigbio/.../CHANGELOG.md) that resolves to 404. Replace it with a real link (or a relative link) to avoid broken-link failures.
Suggested fix
- See CHANGELOG for what changed: https://github.com/bigbio/.../CHANGELOG.md
+ See CHANGELOG for what changed: link:../CHANGELOG.md[CHANGELOG]📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ==== 2. CHANGELOG (at the time of the change) | |
| When the change is accepted and a new version is released, the `CHANGELOG.md` records: | |
| * What changed (e.g., "column X moved from required to optional"). | |
| * Why it changed (link to the GitHub issue). | |
| * Which template versions are affected (e.g., "human v1.2.0, vertebrates v1.2.0"). | |
| * What users need to do (e.g., "update your `comment[sdrf template]` to `human v1.2.0`; or keep `human v1.1.0` if you need the old behavior"). | |
| The CHANGELOG is the permanent human-readable record of all changes. | |
| ==== 3. Validator Messages (after the change) | |
| The validator (sdrf-pipelines) is how most users discover that a newer version exists. Each sdrf-pipelines release ships with the full catalog of template versions. When it validates a file, it compares the declared template version to the latest available and reports: | |
| [source] | |
| ---- | |
| 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/.../CHANGELOG.md | |
| ---- | |
| ==== 2. CHANGELOG (at the time of the change) | |
| When the change is accepted and a new version is released, the `CHANGELOG.md` records: | |
| * What changed (e.g., "column X moved from required to optional"). | |
| * Why it changed (link to the GitHub issue). | |
| * Which template versions are affected (e.g., "human v1.2.0, vertebrates v1.2.0"). | |
| * What users need to do (e.g., "update your `comment[sdrf template]` to `human v1.2.0`; or keep `human v1.1.0` if you need the old behavior"). | |
| The CHANGELOG is the permanent human-readable record of all changes. | |
| ==== 3. Validator Messages (after the change) | |
| The validator (sdrf-pipelines) is how most users discover that a newer version exists. Each sdrf-pipelines release ships with the full catalog of template versions. When it validates a file, it compares the declared template version to the latest available and reports: | |
| [source] | |
| ---- | |
| 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: link:../CHANGELOG.md[CHANGELOG] | |
| ---- |
🤖 Prompt for AI Agents
In `@sdrf-proteomics/VERSIONING.adoc` around lines 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.
Contributor
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.
|
|
||
| === Template Inheritance and Updates | ||
|
|
||
| Templates follow a layered hierarchy where child templates inherit from parent templates (see link:metadata-guidelines/template-definitions.adoc[Template Definitions Guide]). When a parent template is updated, the following rules apply: |
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify that cross-referenced documentation files exist
echo "Checking for cross-referenced documentation files..."
# List all files in sdrf-proteomics directory to understand structure
echo "=== Files in sdrf-proteomics directory ==="
fd -t f . sdrf-proteomics/ | head -30
echo ""
echo "=== Checking for specific cross-referenced files ==="
# Check for template-definitions.adoc
echo "Searching for template-definitions.adoc..."
fd "template-definitions\.adoc" sdrf-proteomics/
# Check for README.adoc
echo ""
echo "Searching for README.adoc..."
fd "README\.adoc" sdrf-proteomics/
# Check for open-issues.adoc
echo ""
echo "Searching for open-issues.adoc..."
fd "open-issues\.adoc" sdrf-proteomics/
# Check for any .adoc files in the directory
echo ""
echo "=== All .adoc files in sdrf-proteomics ==="
fd "\.adoc$" sdrf-proteomics/ | sortRepository: bigbio/proteomics-sample-metadata
Length of output: 3543
🏁 Script executed:
#!/bin/bash
# Check if README.adoc contains a versioning anchor
echo "=== Checking for versioning anchor in README.adoc ==="
rg "^\[\[versioning\]\]|^== .*[Vv]ersion" sdrf-proteomics/README.adoc || echo "No versioning anchor found"
echo ""
echo "=== Checking line 507 in VERSIONING.adoc ==="
sed -n '505,509p' sdrf-proteomics/VERSIONING.adoc | cat -nRepository: bigbio/proteomics-sample-metadata
Length of output: 663
Remove or fix broken reference to open-issues.adoc.
Line 507 references link:open-issues.adoc which does not exist in the repository. Either create the file or remove/replace this reference to prevent broken documentation links. The other cross-references (metadata-guidelines/template-definitions.adoc and the <<versioning>> anchor in README.adoc) are valid.
🤖 Prompt for AI Agents
In `@sdrf-proteomics/VERSIONING.adoc` at 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary by CodeRabbit