diff --git a/.agents/skills/protocol-migration/SKILL.md b/.agents/skills/protocol-migration/SKILL.md index fc2d684..975ef47 100644 --- a/.agents/skills/protocol-migration/SKILL.md +++ b/.agents/skills/protocol-migration/SKILL.md @@ -57,24 +57,18 @@ When migrating: You may normalize formatting only when the meaning is unchanged and unambiguous: - Add a space between numbers and units. -- Standardize temperature formatting to `37 °C`. -- Standardize volume units to `µL`, `mL`, `L`, using the micro sign `µ` consistently. -- Standardize concentration units to `mM`, `µM`, `nM`, `% (w/v)`, etc., using the micro sign `µ` consistently. -- Standardize time units to full words: `seconds`, `minutes`, `hours`. -- Standardize chemical names to match the source but with consistent formatting (e.g. `Tris-HCl` instead of `Tris HCl`). +- Use full-word time units: `seconds`, `minutes`, `hours`. +- Use standard units and spacing, for example `37 °C`, `10 µL`, `1 mM`, `100 nM`. - Standardize pH formatting to `pH 7.4`. -- Standardize chemical formulas with HTML subscripts, for example H2O to H2O. Similarly for other chemical formulas (e.g. MgCl2 to MgCl2). +- Standardize chemical names without changing meaning, for example `Tris-HCl` instead of `Tris HCl`. +- Standardize chemical formulas with HTML subscripts, for example H2O to H2O and MgCl2 to MgCl2. - Do not use Unicode subscript characters such as `₂`. -- Standardize `RNAseq` or `RNA-Seq` to `RNA-seq`. Same for `ChIP-seq`, `ATAC-seq`, etc. -- Use numbered lists for procedural actions in sequence. For other non-procedural content, bullets are better. Note-like text such as Note, NB, Optional, Recommended, and Warning should use blockquote style such as `> **Note**`. -- Normalize bullet formatting and markdown table formatting. -- Normalize heading structure to match the repository template. -- For reaction mixes and anything tabular, place them inside a table as in template. -- For image-based tables, convert to Markdown tables wherever this is legible and unambiguous; otherwise retain the image at the correct protocol location with `CHECK:` explaining why it could not be safely converted. -- Normalize markdown headings, bullets, and tables. -- "Note" or "NOTE" or "NB" or "Optional" or "Recommended" or "Warning" are normalized to start with `>` (example `> **Note**`) and are placed immediately after the step they refer to, or at the end of the protocol if they clearly refer to the whole protocol. +- Standardize names such as `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names. +- Use numbered lists for procedural actions in sequence, bullets for non-procedural lists, and tables for reaction mixes or other tabular content. +- Normalize note-like labels such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note:**`. +- Normalize headings, bullets, Markdown tables, and `Contents` links to match the repository template. +- Convert image-based tables to Markdown tables when legible and unambiguous; otherwise retain the image with `CHECK:`. - Remove empty columns from tables. -- Synchronize `Contents` with actual headings in the protocol. ## Disallowed changes - Do not infer omitted concentrations, times, temperatures, or volumes. @@ -92,30 +86,23 @@ You may normalize formatting only when the meaning is unchanged and unambiguous: - Do not omit protocol-relevant images, image-based tables, figures, diagrams, or visual instructions. ## Output requirements -- edit `README.md` -- use the template headings exactly -- use the template headings in `README.md` -- keep all source content -- add `CHECK:` markers for uncertainty -- use `CHECK:` only for genuine unresolved uncertainty. If no uncertainty remains, do not mention `CHECK:` at all -- add `# Migration notes` -- after drafting, add a short summary in `# Migration notes` covering: +- Only edit `README.md`. +- Use the template headings exactly. +- Keep all source content. +- Keep the Ule Lab Protocol Template attribution badge at the top of the file, but do not add or preserve a template release-version badge. +- Remove the template instruction note and the "Template repository: Click `Use this template`..." note. +- Add `CHECK:` markers only for genuine unresolved uncertainty. +- Add an `# Migration notes` section covering: + - imported protocol metadata from `source-metadata.yml`, using only non-blank lines + - `template_version` from `template-metadata.yml` - formatting normalizations performed - ambiguities and uncertainty flagged - content placed in `## Unplaced content` -- add `# Migration notes` including: - - imported protocol metadata from `source-metadata.yml`, using only the non-blank lines - - template_version from `template-metadata.yml` - - ambiguous mappings - - normalized formatting changes - extracted images converted to Markdown tables - extracted images retained in `README.md` - extracted images omitted because they were decorative or duplicated non-protocol content - - extracted images that could not be confidently classified or converted, marked with `CHECK:` + - extracted images that could not be confidently classified or converted - content copied verbatim but not confidently placed -- keep `[![Created with Ule Lab Protocol Template](https://img.shields.io/badge/created%20with-Ule%20Lab%20Protocol%20Template-blue)](https://github.com/ulelab/protocol-template)` at the top of the file -- remove the template instruction note -- delete the "Template repository: Click `Use this template` to create a new protocol repo..." note ## Verification After drafting, verify the migration against the source: diff --git a/.claude/skills/protocol-migration/SKILL.md b/.claude/skills/protocol-migration/SKILL.md index fc2d684..975ef47 100644 --- a/.claude/skills/protocol-migration/SKILL.md +++ b/.claude/skills/protocol-migration/SKILL.md @@ -57,24 +57,18 @@ When migrating: You may normalize formatting only when the meaning is unchanged and unambiguous: - Add a space between numbers and units. -- Standardize temperature formatting to `37 °C`. -- Standardize volume units to `µL`, `mL`, `L`, using the micro sign `µ` consistently. -- Standardize concentration units to `mM`, `µM`, `nM`, `% (w/v)`, etc., using the micro sign `µ` consistently. -- Standardize time units to full words: `seconds`, `minutes`, `hours`. -- Standardize chemical names to match the source but with consistent formatting (e.g. `Tris-HCl` instead of `Tris HCl`). +- Use full-word time units: `seconds`, `minutes`, `hours`. +- Use standard units and spacing, for example `37 °C`, `10 µL`, `1 mM`, `100 nM`. - Standardize pH formatting to `pH 7.4`. -- Standardize chemical formulas with HTML subscripts, for example H2O to H2O. Similarly for other chemical formulas (e.g. MgCl2 to MgCl2). +- Standardize chemical names without changing meaning, for example `Tris-HCl` instead of `Tris HCl`. +- Standardize chemical formulas with HTML subscripts, for example H2O to H2O and MgCl2 to MgCl2. - Do not use Unicode subscript characters such as `₂`. -- Standardize `RNAseq` or `RNA-Seq` to `RNA-seq`. Same for `ChIP-seq`, `ATAC-seq`, etc. -- Use numbered lists for procedural actions in sequence. For other non-procedural content, bullets are better. Note-like text such as Note, NB, Optional, Recommended, and Warning should use blockquote style such as `> **Note**`. -- Normalize bullet formatting and markdown table formatting. -- Normalize heading structure to match the repository template. -- For reaction mixes and anything tabular, place them inside a table as in template. -- For image-based tables, convert to Markdown tables wherever this is legible and unambiguous; otherwise retain the image at the correct protocol location with `CHECK:` explaining why it could not be safely converted. -- Normalize markdown headings, bullets, and tables. -- "Note" or "NOTE" or "NB" or "Optional" or "Recommended" or "Warning" are normalized to start with `>` (example `> **Note**`) and are placed immediately after the step they refer to, or at the end of the protocol if they clearly refer to the whole protocol. +- Standardize names such as `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names. +- Use numbered lists for procedural actions in sequence, bullets for non-procedural lists, and tables for reaction mixes or other tabular content. +- Normalize note-like labels such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note:**`. +- Normalize headings, bullets, Markdown tables, and `Contents` links to match the repository template. +- Convert image-based tables to Markdown tables when legible and unambiguous; otherwise retain the image with `CHECK:`. - Remove empty columns from tables. -- Synchronize `Contents` with actual headings in the protocol. ## Disallowed changes - Do not infer omitted concentrations, times, temperatures, or volumes. @@ -92,30 +86,23 @@ You may normalize formatting only when the meaning is unchanged and unambiguous: - Do not omit protocol-relevant images, image-based tables, figures, diagrams, or visual instructions. ## Output requirements -- edit `README.md` -- use the template headings exactly -- use the template headings in `README.md` -- keep all source content -- add `CHECK:` markers for uncertainty -- use `CHECK:` only for genuine unresolved uncertainty. If no uncertainty remains, do not mention `CHECK:` at all -- add `# Migration notes` -- after drafting, add a short summary in `# Migration notes` covering: +- Only edit `README.md`. +- Use the template headings exactly. +- Keep all source content. +- Keep the Ule Lab Protocol Template attribution badge at the top of the file, but do not add or preserve a template release-version badge. +- Remove the template instruction note and the "Template repository: Click `Use this template`..." note. +- Add `CHECK:` markers only for genuine unresolved uncertainty. +- Add an `# Migration notes` section covering: + - imported protocol metadata from `source-metadata.yml`, using only non-blank lines + - `template_version` from `template-metadata.yml` - formatting normalizations performed - ambiguities and uncertainty flagged - content placed in `## Unplaced content` -- add `# Migration notes` including: - - imported protocol metadata from `source-metadata.yml`, using only the non-blank lines - - template_version from `template-metadata.yml` - - ambiguous mappings - - normalized formatting changes - extracted images converted to Markdown tables - extracted images retained in `README.md` - extracted images omitted because they were decorative or duplicated non-protocol content - - extracted images that could not be confidently classified or converted, marked with `CHECK:` + - extracted images that could not be confidently classified or converted - content copied verbatim but not confidently placed -- keep `[![Created with Ule Lab Protocol Template](https://img.shields.io/badge/created%20with-Ule%20Lab%20Protocol%20Template-blue)](https://github.com/ulelab/protocol-template)` at the top of the file -- remove the template instruction note -- delete the "Template repository: Click `Use this template` to create a new protocol repo..." note ## Verification After drafting, verify the migration against the source: diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 2bf6589..d84b620 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -49,24 +49,18 @@ When migrating: ## Allowed formatting normalization You may normalize formatting only when the meaning is unchanged and unambiguous: - Add a space between numbers and units. -- Standardize temperature formatting to `37 °C`. -- Standardize volume units to `µL`, `mL`, `L`, using the micro sign `µ` consistently. -- Standardize concentration units to `mM`, `µM`, `nM`, `% (w/v)`, etc., using the micro sign `µ` consistently. -- Standardize time units to full words: `seconds`, `minutes`, `hours`. -- Standardize chemical names to match the source but with consistent formatting (e.g. `Tris-HCl` instead of `Tris HCl`). +- Use full-word time units: `seconds`, `minutes`, `hours`. +- Use standard units and spacing, for example `37 °C`, `10 µL`, `1 mM`, `100 nM`. - Standardize pH formatting to `pH 7.4`. -- Standardize chemical formulas with HTML subscripts, for example H2O to H2O. Similarly for other chemical formulas (e.g. MgCl2 to MgCl2). +- Standardize chemical names without changing meaning, for example `Tris-HCl` instead of `Tris HCl`. +- Standardize chemical formulas with HTML subscripts, for example H2O to H2O and MgCl2 to MgCl2. - Do not use Unicode subscript characters such as `₂`. -- Standardize `RNAseq` or `RNA-Seq` to `RNA-seq`. Same for `ChIP-seq`, `ATAC-seq`, etc. -- Use numbered lists for procedural actions in sequence. For other non-procedural content, bullets are better. Note-like text such as Note, NB, Optional, Recommended, and Warning should use blockquote style such as `> **Note**`. -- Normalize bullet formatting and markdown table formatting. -- Normalize heading structure to match the repository template. -- For reaction mixes and anything tabular, place them inside a table as in template. -- For image-based tables, convert to Markdown tables wherever this is legible and unambiguous; otherwise retain the image at the correct protocol location with `CHECK:` explaining why it could not be safely converted. -- Normalize markdown headings, bullets, and tables. -- "Note" or "NOTE" or "NB" or "Optional" or "Recommended" or "Warning" are normalized to start with `>` (example `> **Note**`) and are placed immediately after the step they refer to, or at the end of the protocol if they clearly refer to the whole protocol. +- Standardize names such as `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names. +- Use numbered lists for procedural actions in sequence, bullets for non-procedural lists, and tables for reaction mixes or other tabular content. +- Normalize note-like labels such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note:**`. +- Normalize headings, bullets, Markdown tables, and `Contents` links to match the repository template. +- Convert image-based tables to Markdown tables when legible and unambiguous; otherwise retain the image with `CHECK:`. - Remove empty columns from tables. -- Synchronize `Contents` with actual headings in the protocol. ## Disallowed changes - Do not infer omitted concentrations, times, temperatures, or volumes. @@ -85,27 +79,23 @@ You may normalize formatting only when the meaning is unchanged and unambiguous: ## Output requirements When drafting a migrated protocol: +- Only edit `README.md`. - Use the template headings exactly. -- Use the template headings in `README.md`. - Keep all source content. -- Add `CHECK:` markers for uncertainty. -- Use `CHECK:` only for genuine unresolved uncertainty. If no uncertainty remains, do not mention `CHECK:` at all. -- Add an `# Migration notes` section listing: +- Keep the Ule Lab Protocol Template attribution badge at the top of the file, but do not add or preserve a template release-version badge. +- Remove the template instruction note and the "Template repository: Click `Use this template`..." note. +- Add `CHECK:` markers only for genuine unresolved uncertainty. +- Add an `# Migration notes` section covering: + - imported protocol metadata from `source-metadata.yml`, using only non-blank lines + - `template_version` from `template-metadata.yml` - formatting normalizations performed - ambiguities and uncertainty flagged - content placed in `## Unplaced content` - - Imported protocol metadata from `source-metadata.yml`, using only the non-blank lines. - - template_version from `template-metadata.yml`. - - ambiguous mappings. - - normalized formatting changes. - - extracted images converted to Markdown tables. - - extracted images retained in `README.md`. - - extracted images omitted because they were decorative or duplicated non-protocol content. - - extracted images that could not be confidently classified or converted, marked with `CHECK:`. - - content copied verbatim but not confidently placed. -- Keep `[![Created with Ule Lab Protocol Template](https://img.shields.io/badge/created%20with-Ule%20Lab%20Protocol%20Template-blue)](https://github.com/ulelab/protocol-template)` at the top of the file. -- Delete the "Template repository: Click `Use this template` to create a new protocol repo..." note. -- Remove the template instruction note. + - extracted images converted to Markdown tables + - extracted images retained in `README.md` + - extracted images omitted because they were decorative or duplicated non-protocol content + - extracted images that could not be confidently classified or converted + - content copied verbatim but not confidently placed ## Verification After drafting, verify the migration against the source: diff --git a/.github/workflows/pdf_header.tex b/.github/workflows/pdf_header.tex index 43fea5c..864636c 100644 --- a/.github/workflows/pdf_header.tex +++ b/.github/workflows/pdf_header.tex @@ -30,11 +30,20 @@ \pagestyle{fancy} \fancyhf{} +\setlength{\headheight}{14pt} -\fancyhead[L]{\small\href{\repoURL}{\nolinkurl{\repoURL}}} -\fancyhead[R]{\small\textbf{Commit:} \href{\commitURL}{\githash}\ \textbar\ \texttt{\gitactor}} +\fancyhead[L]{% + \begin{minipage}[t]{0.54\textwidth} + \raggedright\scriptsize\href{\repoURL}{\nolinkurl{\repoURL}} + \end{minipage}% +} +\fancyhead[R]{% + \begin{minipage}[t]{0.44\textwidth} + \raggedleft\scriptsize\textbf{Commit:} \href{\commitURL}{\githash}\ \textbar\ \texttt{\gitactor} + \end{minipage}% +} \fancyfoot[C]{\thepage} \renewcommand{\headrulewidth}{0.4pt} -\renewcommand{\footrulewidth}{0pt} \ No newline at end of file +\renewcommand{\footrulewidth}{0pt} diff --git a/.github/workflows/readme-to-pdf.yml b/.github/workflows/readme-to-pdf.yml index 5e6b89f..905c6fb 100644 --- a/.github/workflows/readme-to-pdf.yml +++ b/.github/workflows/readme-to-pdf.yml @@ -113,6 +113,11 @@ jobs: -e 's/`\[X\]`/\\FAILstatus{}/g' \ README._pdf.md > README._pdf.tmp && mv README._pdf.tmp README._pdf.md + - name: Render HTML subscripts for PDF only + run: | + set -euo pipefail + sed -E 's|([^<]+)|\\textsubscript{\1}|g' README._pdf.md > README._pdf.tmp && mv README._pdf.tmp README._pdf.md + - name: Create PDF metadata definitions run: | set -euo pipefail diff --git a/.github/workflows/validate-protocol.yml b/.github/workflows/validate-protocol.yml index 2406a3d..a45b745 100644 --- a/.github/workflows/validate-protocol.yml +++ b/.github/workflows/validate-protocol.yml @@ -74,11 +74,23 @@ jobs: python -m unittest discover -s tests -p 'test_*.py' - name: Run content validation + id: content_validation if: steps.validation_gate.outputs.should_validate == 'true' + continue-on-error: true run: | python scripts/validate_protocol_content.py README.md - name: Run style validation + id: style_validation if: steps.validation_gate.outputs.should_validate == 'true' + continue-on-error: true run: | python scripts/validate_protocol_style.py README.md + + - name: Fail if README validation failed + if: ${{ steps.validation_gate.outputs.should_validate == 'true' && (steps.content_validation.outcome != 'success' || steps.style_validation.outcome != 'success') }} + run: | + echo "README validation failed." + echo "Content validation outcome: ${{ steps.content_validation.outcome }}" + echo "Style validation outcome: ${{ steps.style_validation.outcome }}" + exit 1 diff --git a/README.md b/README.md index f3fe486..f2d3e8f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ [![Created with Ule Lab Protocol Template](https://img.shields.io/badge/created%20with-Ule%20Lab%20Protocol%20Template-blue)](https://github.com/ulelab/protocol-template) -[![Template version](https://img.shields.io/github/v/release/ulelab/protocol-template)](https://github.com/ulelab/protocol-template/releases) > Template repository: Click `Use this template` to create a new protocol repo. Template docs are in [docs/USING_THIS_TEMPLATE.md](https://github.com/ulelab/protocol-template/blob/main/docs/USING_THIS_TEMPLATE.md) # TODO: Protocol title diff --git a/docs/PROMPT.md b/docs/PROMPT.md index 50eee0a..015ce6d 100644 --- a/docs/PROMPT.md +++ b/docs/PROMPT.md @@ -9,7 +9,7 @@ Apply those instructions even if you are not GitHub Copilot. Do not change protocol meaning. Use `legacy/source.md` as the primary source when rewriting `README.md`. Use `legacy/source.txt` only as a fallback when `legacy/source.md` looks malformed, incomplete, or unclear. -Use the PDF file in `legacy/` as the final reference source of truth for tables, figures, layout-dependent content, and anything still ambiguous after checking the generated text sources. +Use the PDF file in `legacy/` as the final reference source of truth for tables, figures, layout-dependent content, and anything still ambiguous. Treat image references in `legacy/source.md` and files in `legacy/images/` as extracted protocol content, not decorative artifacts, until they have been reviewed. If `legacy/source.md` and `legacy/source.txt` disagree, prefer `legacy/source.md` for general structure and prose, but use the original PDF as the final tie-breaker. @@ -51,26 +51,21 @@ When migrating: - mention in `# Migration notes` which extracted images were converted to Markdown tables, which were retained as images, which were omitted as non-protocol/decorative, and which require `CHECK:` ## Allowed formatting normalization -Normalize formatting only when the meaning is unchanged and unambiguous: - -- add a space between numbers and units -- use `seconds`, `minutes`, `hours` -- use `µL`, `mL`, `L` -- use `37 °C` style temperature formatting -- standardize concentration units to `mM`, `µM`, `nM`, `% (w/v)`, etc., using the micro sign `µ` consistently -- standardize pH formatting to `pH 7.4` -- standardize chemical names to match the source but with consistent formatting, for example `Tris-HCl` instead of `Tris HCl` -- standardize chemical formulas with HTML subscripts, for example H2O to H2O and MgCl2 to MgCl2 -- do not use Unicode subscript characters such as `₂` -- standardize `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names -- Use numbered lists for procedural actions in sequence. For other non-procedural content, bullets are better. Note-like text such as Note, NB, Optional, Recommended, and Warning should use blockquote style such as `> **Note**`. -- normalize bullets, headings, and markdown tables to match the repository template -- use tables for reaction mixes and other tabular content -- convert image-based tables to Markdown tables wherever this is legible and unambiguous; otherwise retain the image at the correct protocol location with `CHECK:` explaining why it could not be safely converted -- normalize note-like text such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note**` -- place note-like text immediately after the step it refers to, or at the end of the protocol if it clearly refers to the whole protocol -- remove empty columns from tables -- synchronize `Contents` with the actual headings in the protocol +You may normalize formatting only when the meaning is unchanged and unambiguous: + +- Add a space between numbers and units. +- Use full-word time units: `seconds`, `minutes`, `hours`. +- Use standard units and spacing, for example `37 °C`, `10 µL`, `1 mM`, `100 nM`. +- Standardize pH formatting to `pH 7.4`. +- Standardize chemical names without changing meaning, for example `Tris-HCl` instead of `Tris HCl`. +- Standardize chemical formulas with HTML subscripts, for example H2O to H2O and MgCl2 to MgCl2. +- Do not use Unicode subscript characters such as `₂`. +- Standardize names such as `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names. +- Use numbered lists for procedural actions in sequence, bullets for non-procedural lists, and tables for reaction mixes or other tabular content. +- Normalize note-like labels such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note:**`. +- Normalize headings, bullets, Markdown tables, and `Contents` links to match the repository template. +- Convert image-based tables to Markdown tables when legible and unambiguous; otherwise retain the image with `CHECK:`. +- Remove empty columns from tables. ## Disallowed changes - do not infer omitted concentrations, times, temperatures, or volumes @@ -90,28 +85,21 @@ Normalize formatting only when the meaning is unchanged and unambiguous: ## Output requirements - Only edit `README.md`. - Use the template headings exactly. -- Use the template headings in `README.md`. - Keep all source content. -- Add `CHECK:` markers for uncertainty. -- Use `CHECK:` only for genuine unresolved uncertainty. If no uncertainty remains, do not mention `CHECK:` at all. -- Add an `# Migration notes` section. -- After drafting, add a short summary in `# Migration notes` covering: +- Keep the Ule Lab Protocol Template attribution badge at the top of the file, but do not add or preserve a template release-version badge. +- Remove the template instruction note and the "Template repository: Click `Use this template`..." note. +- Add `CHECK:` markers only for genuine unresolved uncertainty. +- Add an `# Migration notes` section covering: + - imported protocol metadata from `source-metadata.yml`, using only non-blank lines + - `template_version` from `template-metadata.yml` - formatting normalizations performed - ambiguities and uncertainty flagged - content placed in `## Unplaced content` -- Include the following in `# Migration notes`: - - imported protocol metadata from `source-metadata.yml`, using only the non-blank lines - - template_version from `template-metadata.yml` - - ambiguous mappings - - normalized formatting changes - extracted images converted to Markdown tables - extracted images retained in `README.md` - extracted images omitted because they were decorative or duplicated non-protocol content - - extracted images that could not be confidently classified or converted, marked with `CHECK:` + - extracted images that could not be confidently classified or converted - content copied verbatim but not confidently placed -- Keep `[![Created with Ule Lab Protocol Template](https://img.shields.io/badge/created%20with-Ule%20Lab%20Protocol%20Template-blue)](https://github.com/ulelab/protocol-template)` at the top of the file. -- Remove the template instruction note. -- Delete the "Template repository: Click `Use this template` to create a new protocol repo..." note. ## Verification After drafting, verify the migration against the source: diff --git a/docs/USING_THIS_TEMPLATE.md b/docs/USING_THIS_TEMPLATE.md index b7ab309..8949e5d 100644 --- a/docs/USING_THIS_TEMPLATE.md +++ b/docs/USING_THIS_TEMPLATE.md @@ -32,7 +32,10 @@ If you are new to GitHub, start with this short [GitHub Hello World tutorial](ht - [Make changes to an existing protocol](#make-changes-to-an-existing-protocol) - [Use the protocol in the lab](#use-the-protocol-in-the-lab) - [Release a protocol](#release-a-protocol) +- [Tips for making the most of the template](#tips-for-making-the-most-of-the-template) - [Citation information](#citation-information) +- [Maintainer and contributor notes (template maintainers only)](#maintainer-and-contributor-notes) + --- # Create a new protocol repository @@ -51,6 +54,10 @@ You now have your own copy of the template. The structure of the template is: ```md . +├── .agents +│ └── skills/protocol-migration/ # Codex migration skill +├── .claude +│ └── skills/protocol-migration/ # Claude Code migration skill ├── .github │ ├── workflows/ # Automation for validations and PDF generation │ └── copilot-instructions.md # AI-assisted migration instructions @@ -99,7 +106,7 @@ The main file you must edit for protocol content is `README.md`. **Do not rename 10. The validation GitHub Actions workflow (`validate-protocol-README`) will automatically run on that pull request when `README.md` has changed. It runs a content check for the required title, status line, status legend, key headings, unresolved placeholders, and placeholder step names, plus a style check for unit formatting. If checks fail, fix them before merging into `main`. 11. Ask for a reviewer where possible. -> **Review scope**: Before opening the pull request, check the changed files. For a routine protocol edit, only `README.md` or `CODEOWNERS` should change. This does not apply to the one-time legacy PDF import workflow, where files in `legacy/` may also be created or updated. If any other files changed, remove those changes or explain clearly why they are needed. +> **Review scope**: Before opening the pull request, check the changed files. For a routine protocol edit, expected changes are `README.md`, `CODEOWNERS`, and optionally `legacy/source-metadata.yml` when provenance is updated. This does not apply to the one-time legacy PDF import workflow, where files in `legacy/` may also be created or updated. If any other files changed, remove those changes or explain clearly why they are needed. > **Note**: Always check accuracy and make sure required sections, such as protocol status and the status legend, are present. @@ -175,7 +182,7 @@ At minimum, make sure your protocol includes: - a status legend row containing `[OK]`, `[?]`, and `[X]` - a short description (`# About`) - contents (`## Contents`) -- a materials section (`# ... Materials`) +- a top-level materials section, optionally numbered, for example `# Materials` or `# 7. Materials` > **Note**: These are mandatory items for validation. @@ -283,15 +290,10 @@ If you want to adapt or improve an existing protocol on GitHub: 10. If the PDF is not generated within a few minutes (you may need to refresh the page), go to the GitHub **Actions** tab, manually run the `README-to-pdf` workflow, and select your working branch in the **Use workflow from** branch menu. 11. PDF generation creates another commit, usually with a message like `Update .pdf`. 12. Before making any further local changes after pushing, run `git pull`. GitHub Actions may have added a new commit on your branch. -13. If you have questions about a protocol, or want to propose a change, open a GitHub Issue using the `Protocol issues` template and assign relevant people. -14. If you are developing a protocol as a team, you can use a GitHub Project. -15. Use Issues to track optimisation ideas or questions. -16. Add images, gels, notes or links to code or data to the relevant Issue. -17. Close the Issue when the question is resolved. -18. This helps keep a record of what has already been tried. -19. If your change should become part of the main protocol, open a pull request to `main` and request review from relevant people. -20. Before requesting review, check the changed files. For a routine protocol edit, only `README.md` or `CODEOWNERS` should change. For a legacy PDF import, files in `legacy/` may also be created or updated. If any other files changed, remove those changes or explain clearly why they are needed. -21. Do not merge into `main` without review, unless you are the only person using that protocol. +13. For issue tracking, Projects, branches, commits, pull requests, and Slack notifications, follow [Tips for making the most of the template](#tips-for-making-the-most-of-the-template). +14. If your change should become part of the main protocol, open a pull request to `main` and request review from relevant people. +15. Before requesting review, check the changed files. For a routine protocol edit, expected changes are `README.md`, `CODEOWNERS`, and optionally `legacy/source-metadata.yml` when provenance is updated. For a legacy PDF import, files in `legacy/` may also be created or updated. If any other files changed, remove those changes or explain clearly why they are needed. +16. Do not merge into `main` without review, unless you are the only person using that protocol. --- @@ -329,10 +331,62 @@ Before using a protocol in the lab, check all of the following: # Release a protocol -Once a protocol has been added and confirmed to be working — that is, its status is 🟢 `[OK]` and this is clearly marked at the top of the file, create the first release: `1.0.0`. -> **Recommended**: Link releases to Zenodo if you want each protocol version to have a citable DOI. +Once a protocol has been added and confirmed to be working, create the first release: `1.0.0`. + +Before releasing: + +1. Confirm the protocol status is 🟢 `[OK]`. +2. Confirm validation passes on `main`. +3. Confirm the generated PDF is current and the PDF header commit SHA matches the protocol commit you intend to release. +4. Create a GitHub release and tag, starting with `1.0.0`. +5. Link the release to Zenodo if you want a citable DOI. +6. Tell maintainers listed in `CODEOWNERS` and relevant protocol users when a new version is released. + +Further changes can then be released using semantic versioning. + +--- + +# Tips for making the most of the template + +Use the repository as both the current protocol and the record of how the protocol changed. + +### Issues and Projects + +- Open one GitHub Issue per problem, optimisation, question, or protocol aspect. Use the `Protocol issues` template. +- Keep issues modular: if the discussion splits into a separate problem, open a separate issue and link it. If an issue is complex, open sub-issues. +- Link issues to a GitHub Project when work is shared, ongoing, or has multiple follow-up steps. +- Add useful evidence directly to the issue: images, gels, follow-up results, notes, links to analysis repositories, database records, sample sheets, or source data. +- Close the issue when the result is incorporated into `README.md`, rejected with a clear reason, or moved to a new issue. Add comments to explain the reason and to discuss an issue. + +### Branches, commits, and pull requests + +- Create a branch for each meaningful feature, fix, or experimental optimisation round. Use the appropriate base branch; it does not always need to be `main`. +- Keep commits small and descriptive. +- Mention related issues in commit messages or pull requests, for example `refs #12` while investigating or `closes #12` when the change resolves the issue. +- In pull requests, request reviewers, tag relevant people, and invite discussion before merging changes that affect how people run or interpret the protocol. + +### Slack integration + +If your team uses Slack, you can connect a protocol repository to a Slack channel with the [GitHub integration for Slack](https://github.com/integrations/slack). In the relevant Slack channel: + +```text +/invite @github +/github signin +/github subscribe owner/repo +``` + +Replace `owner/repo` with the protocol repository, for example `ulelab/protocol-rnaseq`. + +You can set what type of notifications you want updates for on Slack by specifying the type of subscription: + +Examples: +```text +/github subscribe owner/repo issues pulls reviews comments +/github subscribe owner/repo workflows +/github unsubscribe owner/repo commits +``` -Further changes can then be released using semantic versioning. Ensure maintainers listed in `CODEOWNERS` and other protocol developers and users are involved or aware if a new version release is planned. +Use Slack notifications to keep the channel aware of issues, pull requests, reviews, and workflow status. Tune subscriptions if the channel becomes noisy. --- @@ -356,3 +410,54 @@ Template citation: Ira A. Iosub. `protocol-template`, DOI: https://doi.org/10.5281/zenodo.20148013 The template citation metadata is stored in `docs/template-metadata.yml`. + +--- + +# Maintainer and contributor notes + +> **Template maintainers only:** This section is for people maintaining `ulelab/protocol-template` itself. It is not part of the normal protocol-author workflow; most users can stop at [Citation information](#citation-information). + +> **Note:** The template `README.md` intentionally contains placeholders, so content validation may fail in this template repository. Protocol repositories created from the template should pass content validation after the placeholders are replaced. + +## When to change this template + +Change this repository only when the change should apply to future protocol repositories or to the shared template machinery. + +> **Important:** Existing protocol repositories do not automatically inherit changes made here after they were created from the template. If a template change is important for existing protocol repositories, communicate it separately or apply it to those repositories directly. + +Good reasons to change the template include: + +- improving the default protocol structure in `README.md` +- clarifying the user guide +- changing validation or style-fix rules +- improving legacy PDF migration support +- adjusting PDF rendering +- updating shared issue, pull request, or ownership defaults +- updating template metadata, licensing, notices, or release information + +For a one-off correction to a single protocol, change that protocol repository instead. + +## Keep the user experience lightweight + +The template should make the common path obvious: create a repository, edit `README.md`, validate, review, and use the generated PDF. + +- Do not add new required user steps unless they prevent a real recurring failure. +- Prefer improving existing workflows, scripts, or docs over adding new files. +- Keep maintainer rationale out of the main protocol-author path. +- Keep generated or temporary files out of the template unless users need them as examples or defaults. +- Avoid broad rewrites when a small, tested change fixes the problem. + +## Change checklist + +Before merging template changes: + +1. For Markdown-only documentation changes, at least inspect the rendered Markdown or diff carefully. +2. For PDF rendering changes, generate or inspect the PDF produced by the `README-to-pdf` workflow. +3. For workflow changes, check triggers, permissions, branch behavior, generated commits, and whether users need to run `git pull` afterwards. +4. For migration behavior changes, keep `docs/PROMPT.md`, `.github/copilot-instructions.md`, `.agents/skills/protocol-migration/SKILL.md`, and `.claude/skills/protocol-migration/SKILL.md` consistent. +5. For validator or fixer changes, add or update exact regression tests for the intended behavior and important false positives. +6. Update this guide if applicable. + +## Releases + +Use template releases for meaningful template changes. Update `docs/template-metadata.yml` when the template version, citation metadata, or release metadata changes. diff --git a/protocol-template.pdf b/protocol-template.pdf index c46ee2e..50efa19 100644 Binary files a/protocol-template.pdf and b/protocol-template.pdf differ diff --git a/scripts/fix_protocol_style.py b/scripts/fix_protocol_style.py index fd4beb8..35a50c8 100644 --- a/scripts/fix_protocol_style.py +++ b/scripts/fix_protocol_style.py @@ -19,11 +19,10 @@ rf"\b(?P{NUMBER_RE})(?P\s*)(?PuL|ul|UL|uM|UM|ug|μL|μM|μg)\b" ) UNIT_RE = re.compile( - rf"\b(?P{NUMBER_RE})(?P\s*)(?PµL|mL|ml|ML|L|l|µg|mg|g|kg|ng|mM|µM|nM|M|μL|μM|μg)\b" + rf"\b(?P{NUMBER_RE})(?P\s*)(?PµL|mL|ml|ML|L|l|µg|mg|g|kg|ng|mM|µM|nM|M)\b" ) TIME_RE = re.compile( - rf"\b(?P{NUMBER_RE})(?P\s*)(?Pseconds?|second|minutes?|minute|hours?|hour|secs?|sec|mins?|min|hrs?|hr|s|h)\b", - re.IGNORECASE, + rf"\b(?P{NUMBER_RE})(?P\s*)(?P(?i:seconds?|minutes?|hours?|secs?|mins?|hrs?)|s|h)\b", ) CHEMICAL_FORMULA_RE = re.compile(r"\b(?P(?:[A-Z][a-z]?\d*){2,})\b") UNICODE_SUBSCRIPT_RE = re.compile(r"\b(?P[A-Za-z₀₁₂₃₄₅₆₇₈₉]+)\b") @@ -70,6 +69,9 @@ "hours": "hour", } UNICODE_SUBSCRIPT_MAP = str.maketrans("₀₁₂₃₄₅₆₇₈₉", "0123456789") +LITERAL_CHEMICAL_FORMULAS = { + "ddH2O": "ddH2O", +} NOTE_LABEL_RE = re.compile( r"^(?P\s*)(?P