Fix readme adoc

[noatgnu]

update adoc for various template to conform with the yaml template

Summary by CodeRabbit

• Documentation

  • Added comprehensive versioning and deprecation policy documentation.
  • Enhanced template creation guide with step-by-step instructions and concrete examples.
  • Added llms.txt availability badge to repository.

• Changes

  • Relaxed metadata requirements across multiple templates, moving fields from required/recommended to optional.
  • Updated DIA acquisition template with new method documentation and optional mass-tolerance columns.
  • Removed deprecated LinkML schema file.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR comprehensively updates SDRF-Proteomics documentation by adding versioning and deprecation policies, expanding template creation guidance with concrete examples, relaxing multiple template metadata field requirements, removing the LinkML schema file, and adding an llms.txt reference documentation.

Changes

Cohort / File(s)	Summary
Documentation Badge & Reference README.md, llms.txt	Added llms.txt availability badge link to README and created comprehensive SDRF-Proteomics documentation file enumerating specification, templates, versioning, tools, examples, and publications.
Core SDRF Versioning & Policy sdrf-proteomics/README.adoc, sdrf-proteomics/VERSIONING.adoc	Added versioning cross-reference and changed comment[technical replicate] from REQUIRED to RECOMMENDED; introduced comprehensive versioning and deprecation policy covering three independently versioned components, compatibility matrix, feature lifecycle, grace periods, and validator operations.
Template Creation Guidance sdrf-proteomics/metadata-guidelines/template-definitions.adoc	Converted minimal template creation section into full end-to-end workflow with concrete top-down template example, structured 7-step guide, expanded YAML schema demonstrating column inheritance/overrides, validation semantics, and PR submission guidance.
Template Requirement Changes sdrf-proteomics/templates/affinity-proteomics/README.adoc, sdrf-proteomics/templates/cell-lines/README.adoc, sdrf-proteomics/templates/human/README.adoc, sdrf-proteomics/templates/metaproteomics/README.adoc	Downgraded multiple metadata columns from RECOMMENDED/REQUIRED to OPTIONAL: comment[plate], characteristics[sampling site], comment[cell line source], characteristics[age], characteristics[sex], and moved characteristics[sample collection method] to recommended.
DIA Template Updates sdrf-proteomics/templates/dia-acquisition/README.adoc	Replaced comment[number of isolation windows] with comment[DIA method], added dual HTML5/non-HTML5 backend table structures, introduced optional precursor mass tolerance and fragment mass tolerance columns, and updated example SDRF content.
Crosslinking Template Simplification sdrf-proteomics/templates/crosslinking/README.adoc	Removed optional characteristics[enrichment process] column entry from crosslinking template.
Schema File Removal sdrf-proteomics/templates/sdrf-template-schema.linkml.yaml	Deleted comprehensive LinkML schema file (377 lines) that defined SDRF proteomics template structure, validation rules, enumerations, and metadata for template YAML files.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Major PR to update some inconsistencies in the specification.  #726 — Modifies SDRF-Proteomics documentation and template files with changes to ontology/technology-related requirements and template specifications.
• Release v1.1.0 changes in the specification [DRAFT PR] #733 — Restructures templates, adds sdrf-templates submodule, and makes extensive template README changes affecting similar template documentation surface.
• Feature lifecycle document #793 — Directly modifies sdrf-proteomics template schema and versioning/lifecycle documentation related to the LinkML schema removal.

Suggested labels

Review effort 3/5

Suggested reviewers

• nithujohn
• timosachsenberg
• levitsky
• enryH
• fabianegli

Poem

🐰 Hop, hop, hooray! — A rabbit's cheer
Templates polished, versioning clear,
Schemas shuffled, requirements eased,
Docs expanded, guidance released!
📚✨ The proteomics path grows bright!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Fix readme adoc' is vague and generic, using non-descriptive terms that don't convey the scope or nature of the substantial changes across multiple template files and documentation.	Consider a more descriptive title that reflects the actual scope, such as 'Update SDRF template documentation to conform with versioning and schema standards' or 'Harmonize template metadata requirements across SDRF documentation'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix-readme-adoc

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

sdrf-proteomics/templates/dia-acquisition/README.adoc (1)

182-220: ⚠️ Potential issue | 🟡 Minor

Remove duplicate Optional Columns section.

Lines 182-220 duplicate content already present in lines 116-178. The "Optional Columns" section appears twice with overlapping column definitions (precursor mass tolerance and fragment mass tolerance). This creates confusion and should be consolidated into a single section.

♻️ Proposed fix

Remove lines 182-220 entirely, as the optional columns are already documented in the earlier section (lines 116-178).

 endif::[]
 
-NOTE: The parent term for all DIA methods is https://www.ebi.ac.uk/ols4/ontologies/pride/classes/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FPRIDE_0000450[Data-independent acquisition (PRIDE:0000450)]. Use `comment[DIA method]` to specify the specific variant when known. Check the https://www.ebi.ac.uk/ols4/ontologies/pride[PRIDE Controlled Vocabulary] for available terms.
-
-=== Optional Columns
-
-The following columns are OPTIONAL but commonly used:
-
-ifdef::backend-html5[]
-++++
-<table class="tableblock frame-all grid-all stretch requirements-table">
-<thead>
-<tr><th>Column</th><th>Requirement</th><th>Description</th><th>Ontology/CV</th><th>Example Values</th></tr>
-</thead>
-<tbody>
-<tr>
-<td><code>comment[precursor mass tolerance]</code></td>
-<td><span class="optional-badge">OPTIONAL</span></td>
-<td>Mass tolerance for precursor ions in database search</td>
-<td>Numeric value with unit</td>
-<td>10 ppm, 20 ppm</td>
-</tr>
-<tr>
-<td><code>comment[fragment mass tolerance]</code></td>
-<td><span class="optional-badge">OPTIONAL</span></td>
-<td>Mass tolerance for fragment ions in database search</td>
-<td>Numeric value with unit</td>
-<td>0.02 Da, 20 ppm</td>
-</tr>
-</tbody>
-</table>
-++++
-endif::[]
-
-ifndef::backend-html5[]
-[cols="2,1,2,1,2", options="header"]
-|===
-|Column Name |Requirement |Description |Ontology/CV |Example Values
-
-|comment[precursor mass tolerance] |OPTIONAL |Mass tolerance for precursor ions in database search |Numeric value with unit |10 ppm, 20 ppm
-|comment[fragment mass tolerance] |OPTIONAL |Mass tolerance for fragment ions in database search |Numeric value with unit |0.02 Da, 20 ppm
-|===
-endif::[]
-
 [[stepped-collision-energy]]
 == Stepped Collision Energy

🤖 Fix all issues with AI agents

In `@llms.txt`:
- Around line 1-121: The "Template YAML Schemas" block refers to the
uninitialized git submodule sdrf-templates (entries like
sdrf-templates/templates.yaml, base/1.1.0/base.yaml,
ms-proteomics/1.1.0/ms-proteomics.yaml, etc.) which is empty; either initialize
and populate that submodule so those files exist and update llms.txt paths to
the real files, or remove the entire "Template YAML Schemas" section (the
sdrf-templates block) from llms.txt; also verify and either add or remove the
annotated-projects/PXD017710/PXD017710.sdrf.tsv reference (update the
annotated-projects list accordingly) so no broken references remain.

In `@README.md`:
- Line 10: Update the badge link in README.md so it points to the correct
repository: replace the URL referencing bigbio/proteomics-metadata-standard with
bigbio/proteomics-sample-metadata (change the llms.txt link from
https://github.com/bigbio/proteomics-metadata-standard/blob/master/llms.txt to
https://github.com/bigbio/proteomics-sample-metadata/blob/master/llms.txt) so
the [![llms.txt](...)] badge points to the existing llms.txt file.

In `@sdrf-proteomics/VERSIONING.adoc`:
- Around line 248-253: The example validator message in VERSIONING.adoc contains
an invalid placeholder URL ("https://github.com/bigbio/.../CHANGELOG.md");
update that string literal in the [source] example so it points to a concrete
changelog path (e.g. the real repo CHANGELOG URL) or use a clear placeholder
format like {CHANGELOG_URL} or https://github.com/bigbio/REPO_NAME/CHANGELOG.md
to satisfy link checkers and make the example valid.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash

# First, let's understand the repository structure
echo "=== Repository Structure ==="
ls -la | head -20

echo -e "\n=== Checking critical documentation files ==="
for file in \
  "sdrf-proteomics/README.adoc" \
  "sdrf-proteomics/quickstart.adoc" \
  "sdrf-proteomics/VERSIONING.adoc" \
  "sdrf-proteomics/metadata-guidelines/sample-metadata.adoc" \
  "sdrf-proteomics/metadata-guidelines/template-definitions.adoc" \
  "sdrf-proteomics/metadata-guidelines/sdrf-terms.tsv" \
  "psi-document/v1.0.0/SDRF_Proteomics_Specification_v1.0.0.pdf" \
  "psi-document/v1.1.0-dev/sdrf-proteomics-specification-v1.1.0-dev.pdf"
do
  if [ -f "$file" ]; then
    echo "✓ EXISTS: $file"
  else
    echo "✗ MISSING: $file"
  fi
done

echo -e "\n=== Checking template README files ==="
for template in ms-proteomics affinity-proteomics human vertebrates invertebrates plants cell-lines dda-acquisition dia-acquisition single-cell immunopeptidomics crosslinking metaproteomics olink somascan
do
  if [ -f "sdrf-proteomics/templates/$template/README.adoc" ]; then
    echo "✓ EXISTS: sdrf-proteomics/templates/$template/README.adoc"
  else
    echo "✗ MISSING: sdrf-proteomics/templates/$template/README.adoc"
  fi
done

echo -e "\n=== Checking sdrf-templates submodule ==="
if [ -d "sdrf-proteomics/sdrf-templates" ]; then
  echo "✓ sdrf-templates directory exists"
  if [ -f "sdrf-proteomics/sdrf-templates/templates.yaml" ]; then
    echo "✓ templates.yaml manifest found"
  else
    echo "✗ MISSING: templates.yaml"
  fi
  
  # Check for template YAML files mentioned
  echo -e "\n=== Checking template YAML files ==="
  for path in \
    "sdrf-proteomics/sdrf-templates/base/1.1.0/base.yaml" \
    "sdrf-proteomics/sdrf-templates/ms-proteomics/1.1.0/ms-proteomics.yaml" \
    "sdrf-proteomics/sdrf-templates/human/1.1.0/human.yaml" \
    "sdrf-proteomics/sdrf-templates/single-cell/1.0.0/single-cell.yaml" \
    "sdrf-proteomics/sdrf-templates/immunopeptidomics/1.0.0-dev/immunopeptidomics.yaml" \
    "sdrf-proteomics/sdrf-templates/metaproteomics/1.0.0-dev/metaproteomics.yaml" \
    "sdrf-proteomics/sdrf-templates/olink/1.0.0/olink.yaml" \
    "sdrf-proteomics/sdrf-templates/somascan/1.0.0/somascan.yaml"
  do
    if [ -f "$path" ]; then
      echo "✓ EXISTS: $path"
    else
      echo "✗ MISSING: $path"
    fi
  done
else
  echo "✗ MISSING: sdrf-templates directory/submodule"
fi

echo -e "\n=== Checking examples directory ==="
for file in \
  "examples/core/PXD002137/PXD002137.sdrf.tsv" \
  "examples/core/PXD004684/PXD004684.sdrf.tsv" \
  "examples/core/PXD006482/PXD006482.sdrf.tsv" \
  "examples/core/PXD008934/PXD008934.sdrf.tsv" \
  "examples/core/PDC000126/PDC000126.sdrf.tsv" \
  "examples/use-cases/crosslinking.sdrf.tsv" \
  "examples/use-cases/immunopeptidomics.sdrf.tsv" \
  "examples/use-cases/single-cell.sdrf.tsv"
do
  if [ -f "$file" ]; then
    echo "✓ EXISTS: $file"
  else
    echo "✗ MISSING: $file"
  fi
done

echo -e "\n=== Checking annotated-projects directory ==="
if [ -d "annotated-projects" ]; then
  echo "✓ annotated-projects directory exists"
  for file in \
    "annotated-projects/PXD008934/PXD008934.sdrf.tsv" \
    "annotated-projects/PXD017710/PXD017710.sdrf.tsv" \
    "annotated-projects/PXD000612/PXD000612.sdrf.tsv" \
    "annotated-projects/PXD018830/PXD018830-DIA.sdrf.tsv" \
    "annotated-projects/PXD000759/PXD000759.sdrf.tsv" \
    "annotated-projects/PXD001819/PXD001819.sdrf.tsv"
  do
    if [ -f "$file" ]; then
      echo "✓ EXISTS: $file"
    else
      echo "✗ MISSING: $file"
    fi
  done
else
  echo "✗ MISSING: annotated-projects directory"
fi

echo -e "\n=== Checking project files ==="
for file in "README.md" "CHANGELOG.md" "CITATION.cff" "LICENSE" "DEVELOPMENT.md"
do
  if [ -f "$file" ]; then
    echo "✓ EXISTS: $file"
  else
    echo "✗ MISSING: $file"
  fi
done

Repository: bigbio/proteomics-sample-metadata

Length of output: 4565

---

🏁 Script executed:

# Check if sdrf-templates is a git submodule
echo "=== Checking .gitmodules ==="
cat .gitmodules

echo -e "\n=== Contents of sdrf-templates directory ==="
ls -la sdrf-proteomics/sdrf-templates/ 2>/dev/null || echo "Directory empty or not readable"

echo -e "\n=== Check git submodule status ==="
git config --file=.gitmodules --name-only --get-regexp path

echo -e "\n=== Detailed submodule info ==="
git config --file=.gitmodules --get-regexp submodule || echo "No submodule configuration found"

echo -e "\n=== Check if llms.txt actually references missing files ==="
grep -n "sdrf-templates" llms.txt | head -20

Repository: bigbio/proteomics-sample-metadata

Length of output: 3068

---

Fix broken references to uninitialized git submodule in llms.txt.

The sdrf-templates git submodule (lines 36–71) is registered but not initialized. The directory exists but is empty, making all referenced YAML files (templates.yaml, base.yaml, ms-proteomics.yaml, etc.) unavailable. This undermines llms.txt's purpose as a navigation guide for LLMs and developers.

Additionally, one annotated project is missing: annotated-projects/PXD017710/PXD017710.sdrf.tsv (referenced line 101).

Required fixes:

1. Either initialize the sdrf-templates submodule and update the llms.txt file to reference the actual paths, or remove the entire "Template YAML Schemas" section (lines 36–71)
2. Remove or verify the reference to annotated-projects/PXD017710/PXD017710.sdrf.tsv

All other documented paths (specification files, template README.adoc files, examples, and annotated projects except PXD017710) are accurate and exist.

🤖 Prompt for AI Agents

In `@llms.txt` around lines 1 - 121, The "Template YAML Schemas" block refers to
the uninitialized git submodule sdrf-templates (entries like
sdrf-templates/templates.yaml, base/1.1.0/base.yaml,
ms-proteomics/1.1.0/ms-proteomics.yaml, etc.) which is empty; either initialize
and populate that submodule so those files exist and update llms.txt paths to
the real files, or remove the entire "Template YAML Schemas" section (the
sdrf-templates block) from llms.txt; also verify and either add or remove the
annotated-projects/PXD017710/PXD017710.sdrf.tsv reference (update the
annotated-projects list accordingly) so no broken references remain.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

# Check if llms.txt file exists in the repository
find . -name "llms.txt" -type f 2>/dev/null

Repository: bigbio/proteomics-sample-metadata

Length of output: 87

---

🏁 Script executed:

# Verify README.md content around line 10
head -20 README.md | cat -n

Repository: bigbio/proteomics-sample-metadata

Length of output: 2661

---

🏁 Script executed:

# List files in the repository root to understand the structure
ls -la | head -20

Repository: bigbio/proteomics-sample-metadata

Length of output: 1287

---

Fix the badge URL to use the correct repository name.

The llms.txt file already exists in the repository. The badge link will fail not because the file is missing, but because the URL references the wrong repository. The badge URL should point to bigbio/proteomics-sample-metadata instead of bigbio/proteomics-metadata-standard.

Correct the URL in line 10 from:

https://github.com/bigbio/proteomics-metadata-standard/blob/master/llms.txt

to:

https://github.com/bigbio/proteomics-sample-metadata/blob/master/llms.txt

🤖 Prompt for AI Agents

In `@README.md` at line 10, Update the badge link in README.md so it points to the
correct repository: replace the URL referencing
bigbio/proteomics-metadata-standard with bigbio/proteomics-sample-metadata
(change the llms.txt link from
https://github.com/bigbio/proteomics-metadata-standard/blob/master/llms.txt to
https://github.com/bigbio/proteomics-sample-metadata/blob/master/llms.txt) so
the [![llms.txt](...)] badge points to the existing llms.txt file.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix the placeholder URL in the example validator message.

The URL contains a literal ... which makes it invalid and causes the link checker to fail. Replace with either a concrete path to the CHANGELOG or use a clear placeholder format.

🔗 Proposed fix

 [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
+  See CHANGELOG for what changed: https://github.com/bigbio/proteomics-metadata-standard/blob/master/CHANGELOG.md
 ----

📝 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

	[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
	----
	[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/proteomics-metadata-standard/blob/master/CHANGELOG.md
	----

🤖 Prompt for AI Agents

In `@sdrf-proteomics/VERSIONING.adoc` around lines 248 - 253, The example
validator message in VERSIONING.adoc contains an invalid placeholder URL
("https://github.com/bigbio/.../CHANGELOG.md"); update that string literal in
the [source] example so it points to a concrete changelog path (e.g. the real
repo CHANGELOG URL) or use a clear placeholder format like {CHANGELOG_URL} or
https://github.com/bigbio/REPO_NAME/CHANGELOG.md to satisfy link checkers and
make the example valid.