From 4b303765f0d3010ef5614365358ac7894bef08d9 Mon Sep 17 00:00:00 2001 From: Karl Kauc Date: Fri, 15 May 2026 22:21:43 +0200 Subject: [PATCH] docs: add top-level CONTRIBUTING.md Captures the conventions enforced throughout the repo so contributors get them right up front: English-only teaching-grade examples, no XML namespace, XSD validation against the official release via tools/fetch-schema.sh, 4.0.0 has no ControlData/Version, Schematron tolerance/pattern rules, secure XML parsing, round-trip proven by xml_equiv + XSD, local verification commands, toolchain gotchas (SchXslt fat-jar classpath, WebDAV .DS_Store), and the branch-off-fresh-main / no-stacked-PRs / maintainer-merges workflow. README Contributing section now links to it. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 11 +++--- 2 files changed, 96 insertions(+), 6 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9b0977a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,91 @@ +# Contributing + +Thanks for improving the FundsXML enterprise examples. This repo is a +**reference**: every example must be runnable, self-explanatory, and verified. +Please read this before opening a pull request. + +## Ground rules + +- **English only.** All code/XML comments, READMEs and docs are in English. +- **Examples are teaching artifacts.** Comment generously: a file-header block + (purpose, exact run command, dependencies, FundsXML assumptions) plus + *what & why* comments on non-obvious logic. A developer should be able to + reimplement the pattern from the comments alone. +- **One README per component**, kept in sync with the code it documents. +- **No new runtime services.** No databases servers, no Docker — examples must + run standalone (SQLite, fetched jars, pure-language libs). + +## FundsXML conventions + +- **FundsXML 4.x has no XML namespace** — use bare element names in XPath; + never introduce a default namespace or prefixes (except `ds:`/`xsi:` where + the schema itself requires them). `xsi:noNamespaceSchemaLocation` must be in + the XMLSchema-instance namespace or validators reject it. +- **Validate against the official released schema**, never a hand-made + catalog: fetch with `tools/fetch-schema.sh ` (it handles GitHub's + 302 redirect and the relative `xmldsig-core-schema.xsd` import that 4.2.9+ + needs). Set sample `xsi:noNamespaceSchemaLocation` to that release URL. +- **4.0.0 `ControlData` has no `` element** (added in 4.1.0) — never + add one to a 4.0.0 sample. +- Positions ↔ Assets link by a shared `UniqueID`; `AssetMasterData` is + document-scoped. Keep Schematron and Basic-XSLT **tolerances identical** + (NAV sum < 1 ccy unit, percentage sum ≤ 1%, price calc < 0.1) and update + both READMEs together when changing one. +- **ISO Schematron matches only the first rule per pattern**: keep at most one + rule per node-context per `` (put others in their own pattern), or + later rules become dead code. +- **Secure XML parsing everywhere**: disable DTDs / external entities + (`resolve_entities=False` + `no_network=True`, `disallow-doctype-decl`, + `XmlResolver=null`, `--nonet`, `FEATURE_SECURE_PROCESSING`). + +## Samples & round-trips + +- New samples must be **XSD-valid** against their version's official schema and + carry a per-example README with a version badge and the validated-against URL. +- Keep the committed positive samples passing; deliberately broken inputs go in + `tests/fixtures/invalid/` and must fail their check (CI asserts this). +- For import/export (round-trip) examples: prove **import file == export file** + with `Database_Integration/tools/xml_equiv.py` (it ignores the volatile + `DocumentGenerated` timestamp and numeric/whitespace/attr-order; child order + is significant) **and** XSD-validate the output — `xml_equiv` ignores + `xmlns`, so the two checks are complementary. Author round-trip fixtures + *lossless* (only model-captured elements) so equality is achievable. + +## Local verification (before you push) + +Run what you changed and confirm it actually works — no "should pass" claims. + +```bash +tools/fetch-schema.sh 4.2.9 # XSD cache (gitignored) +tools/fetch-tools.sh # Saxon / SchXslt / sqlite-jdbc / Santuario + +xmllint --noout --schema .schema-cache/4.2.9/FundsXML.xsd .xml +Schematron_DataQuality_Checks/Basic_Checks/invocation/run-schematron.sh .xml +# DB round-trip example: +python3 Database_Integration/python/import_fundsxml.py fx.db .xml +python3 Database_Integration/python/export_fundsxml.py fx.db out.xml +python3 Database_Integration/tools/xml_equiv.py .xml out.xml +``` + +Toolchain notes: the SchXslt CLI jar bundles its own Saxon — do **not** add the +standalone `Saxon-HE` jar to its classpath. The working tree may sit on a +WebDAV mount that creates `.DS_Store`/`._*` — these are gitignored; never +`git add` them. + +## Pull requests + +- Branch off the **latest `main`** (`git fetch origin && git switch -c origin/main`). + **Do not stack a PR on another unmerged branch** — the repo auto-deletes + head branches on merge, which would orphan your base. +- One focused change per PR; update the relevant README(s) in the same PR. +- CI (`.github/workflows/ci.yml`, job `validate`) must be green — it + fetches schemas, validates every sample (XSD + Schematron), runs the + transform/XQuery/signature/DB/large-file/JSON smoke tests, and asserts the + negative fixtures fail. Confirm green before marking a PR ready. +- A maintainer merges PRs. End commit messages and PR descriptions per the + repo's existing style. + +## Licensing + +By contributing you agree your work is licensed under the repository's +[Apache License 2.0](LICENSE). diff --git a/README.md b/README.md index dd3d5f3..00752d1 100644 --- a/README.md +++ b/README.md @@ -251,12 +251,11 @@ The sample files demonstrate various FundsXML asset types: ## Contributing -Contributions are welcome! Please feel free to submit pull requests with: -- Additional sample FundsXML files -- New Schematron validation rules -- Additional XSLT report templates -- Documentation improvements -- Code examples in other languages +Contributions are welcome — additional samples, rules, report templates, +language examples, and documentation improvements. Please read +**[CONTRIBUTING.md](./CONTRIBUTING.md)** first: it covers the FundsXML +conventions, the secure-XML and round-trip requirements, local verification, +and the branch/PR workflow this repo expects. ## License