PR template

This page renders perseus-PR-template.md from the repository root. That markdown file is the authoritative, copy-and-commit artifact. This is its web-readable form. The evidence behind every checklist item is in the report.

A Template for Successful Pull Requests to PerseusDL/canonical-greekLit

This checklist is reverse-engineered from (a) the repository’s own machinery (the HookTest CI workflow, the __cts__.xml metadata files, and the EpiDoc headers) and (b) the recorded edit histories of the external contributors whose corrections were actually merged (e.g. Aurélien Berra, Michael Konieczny, Thibault Clérice, Ariane Pinche’s group, Chiara Palladino, Helma Dik).

Every push and pull request is validated by HookTest against the EpiDoc/CapiTainS-CTS scheme. If HookTest fails, the file is excluded from the release. Passing HookTest locally before you open the PR is essential to a successful merge.**

---

0. Before you touch anything

• Read the repo Wiki (linked from the README) on contacting the team and submitting corrections.
• Find the work’s CTS URN. Structure is data/TEXTGROUP/WORK/TEXTGROUP.WORK.VERSION.xml (e.g. data/tlg0019/tlg001/tlg0019.tlg001.perseus-grc2.xml = Aristophanes, Acharnians, Perseus Greek edition 2). Use the Perseus Catalog to confirm the URN if unsure.
• Open an issue first describing what you intend to fix, and wait for a maintainer to acknowledge / claim it to you. This avoids duplicated work and signals good faith. Merged contributors consistently coordinated with Babeu / Cerrato / Crane before large changes.
• Fork the repo and work on a branch, not master.
• Confirm you agree to the license: all contributions are CC-BY-SA 4.0, and Perseus credits accepted changes.

1. Set up the validation toolchain (do this once)

• Python 3.11 (HookTest breaks on newer versions) and Java 11.
• pip install "hooktest<2.0.0"
• An XML editor that validates against RelaxNG (oXygen, or VS Code + an XML extension) pointed at the EpiDoc schema: https://epidoc.stoa.org/schema/latest/tei-epidoc.rng

2. Editing rules (what “compliant” means here)

• File is TEI P5 + EpiDoc, with the schema processing instruction at the top: <?xml-model href="https://epidoc.stoa.org/schema/latest/tei-epidoc.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
• The <refsDecl n="CTS"> block has a correct <cRefPattern> for every citation level (book/line/section). The matchPattern regex and the replacementPattern XPath must actually resolve against your <div>/<l> structure. This is where most CTS failures come from.
• The filename URN matches the <idno type="filename">, and the version’s urn matches the __cts__.xml in the work folder.
• If you added or renamed a work/edition, update (or create) the matching __cts__.xml files at both the textgroup and work level (ti:textgroup, ti:work, ti:edition/ti:translation with urn, workUrn, groupUrn, and xml:lang).
• Language is harmonised: @ident/xml:lang are grc for Greek, lat for Latin, eng for English — consistently, in langUsage and on inline elements. (Mismatched language codes are a common HookTest failure and were an explicit part of Berra’s fixes.)
• Text is fully Unicode — no leftover Betacode, stray entities, or duplicated lines. Citation @n values are unique at each level (add a letter suffix, e.g. 10a, if the source duplicates a number).
• The <sourceDesc>/<biblStruct> accurately describes the print edition and, ideally, links to the scan (e.g. an Internet Archive <ref>).

3. Record your work (provenance)

• Add yourself to <titleStmt> with a <respStmt>: xml <respStmt> <persName>Your Name</persName> <orgName>Your Affiliation</orgName> <resp>Digital editor</resp> </respStmt>
• Add a precise <change> at the top of <revisionDesc> (reverse- chronological), ISO date, your name, and a specific description of what you changed — not “edits”. Model entry (Berra): xml <change when="2019-04-06" who="Your Name">Corrected many OCR errors — mostly missing spaces after parentheses and semicolons; restored Greek title in the head tag. Validated with HookTest.</change>

4. Validate locally (the gate)

• Run the exact CI command at the repo root and fix everything it flags: hooktest ./ --console --scheme epidoc --workers 3 --verbose 10 --manifest --countword (To test just your file, point HookTest at its folder.) Your file must be reported as passing before you open the PR.

5. Open the pull request

• One work per PR. Keep the diff focused; small, reviewable PRs merge faster than sprawling ones.
• Commit messages and PR title reference the URN and the issue number.
• PR description states, briefly: the URN, what you corrected/converted, that HookTest passes, and confirmation you’re contributing under CC-BY-SA 4.0.
• Let the GitHub Actions “Hooktest and Release” run complete green.
• Respond promptly and civilly to review comments; make requested changes on the same branch.

What the merge record (2019–2026 git history) actually shows works

Patterns shared by the outside contributors whose work was consistently merged:

• One change, one commit, one file. The most-merged correctors commit ~1 file per commit (Fifield ~1.8, Dik/Beine/Konieczny ~1.0). Big multi-file commits are the exception, and they’re reserved for a single named operation (e.g. “Normalize lang=\"greek\" => lang=\"grc\"” across N files).
• Say exactly what changed, and where. Winning commit messages name the URN and the precise fix: (tlg0005.tlg001.perseus-grc2.xml) add missing first letter of ὡς in 14.22. Avoid “edits” / “text fixes” as your only message.
• Link the issue. Reference the tracking issue number (#1291) so the maintainer can see the report your fix resolves. Nearly all of one intern’s conversions and many correction PRs carry an issue number.
• Use the small-PR web workflow for one-off corrections. Repeated single-fix PRs off you/you-patch-N branches (the pattern Helma Dik used for dozens of merged proofreading fixes) are welcomed and merge fast.
• Pick a lane and stay in it. Successful contributors specialise: a scholar does philological/OCR/diacritic corrections on texts they know; an engineer does markup normalisation or new-edition conversion in bulk. Both are valued.
• Show up regularly. The highest-impact volunteer contributed small fixes steadily across ~5 years rather than in one burst. Consistency builds the reviewer trust that gets later PRs merged with less friction.

6. Etiquette / durable-success habits

• Start small (a single edition’s typo pass) to build trust, then take on larger conversions — this is the arc every successful external contributor followed.
• Prefer real philological value (OCR/Betacode cleanup, restoring missing text, distinguishing text-critical <add>/<del>) over cosmetic reformatting.
• Keep the source-edition bibliography honest; don’t silently “improve” the text away from the printed source it claims to reproduce.
• If you build tooling or scripts to do bulk fixes, say so in the <change> note and in the PR, and spot-check the output by hand.