docs: Codex consistency pass (links, licensing, ADRs, house style)#69
Open
tlmquintino wants to merge 14 commits into
Open
docs: Codex consistency pass (links, licensing, ADRs, house style)#69tlmquintino wants to merge 14 commits into
tlmquintino wants to merge 14 commits into
Conversation
Cross-document consistency and clarity pass across the Codex:
- Broken links: Principles -> Guidelines/External-Contributions; ADR-Guidelines
-> ADR index (README); Example.md maturity badge; Requesting-New-Repository ->
relative link.
- Licensing coherence: populate root LICENSE (Apache 2.0 + ECMWF intergovernmental
notice at the tail) and align Legal/Apache-Licence to it; NOTICE is 'never
empty'; drop the fragile 'line 178' instruction; add the EU-funded ('European
Union') and partner/Crown-Copyright holder rules; add 'reuse annotate' tooling;
disambiguate CONTRIBUTORS vs CONTRIBUTING.md; relabel Legal/README Apache-Licence
entry; fix Example.md 'All rights reserved' -> Apache licence block + maturity
disclaimer; add licensing artefacts (LICENSES/, NOTICE, REUSE.toml, SECURITY.md,
CITATION.cff) to the Repository Structure layout trees.
- ADRs: reconcile ADR-007 status (Accepted); fix ADR-005 title number (004->005)
and index title; normalise Status lines (bold active state, drop template
brackets) and the template; fix ADR-002 heading; reduce ADR-006 to a withdrawal
stub linking MARS-001 (+ back-link in MARS-001).
- Skills<->policy: cross-link Ai-Contributions <-> Agent Skills; reconcile
'mandatory' vs advisory wording; raise AI-code testing to the same bar; soften
the 'CI security scanning' claim in Open-Source-Principles.
- Branching/versioning: ADR-001 = rationale, Branching.md = procedure; fix
v1.9.0->1.9.0 and x.y.z+1; cross-link SemVer conventions.
- Root README Contents: add MARS language; consistent per-section listing; resolve
Code-of-Conduct/Principles asymmetry.
- Overlaps: align Documentation&Training <-> SMP doc platforms; cross-link
Forking <-> External-Contributions.
- Rendering artefacts: de-duplicate indented badge blocks (ESEE, Project Maturity)
and normalise the maturity 'copy this' blocks.
- House style: British spelling (Containerisation, Observability, SMP, ADR-004/007,
ESEE, MARS-002); 'Co-operating States'; MARS typos ('Languge'), empty bullet,
strikethrough/date-format drift; assorted grammar fixes.
- Mark advertised-but-empty sections (Testing, Versioning, C++, Observability
alerting) as WIP; refresh TODO.md.
There was a problem hiding this comment.
Pull request overview
This PR performs a repository-wide documentation consistency pass across Codex: correcting links and cross-references, reconciling licensing guidance and templates, and normalising ADR/MARS record formatting and status labelling to reduce drift and contradictions across documents.
Changes:
- Standardised cross-document references (README contents, ADR index/guidelines, forking/external contributions cross-links) and applied house-style spelling/wording corrections.
- Reconciled licensing guidance and templates (root
LICENSE, updated Apache-Licence template, updated licensing instructions and repository-structure layouts). - Normalised ADR/MARS decision record status formatting and corrected specific ADR/MARS typos/headings/statuses.
Reviewed changes
Copilot reviewed 44 out of 45 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| TODO.md | Reframed remaining gaps as content WIP and recorded items resolved by the consistency pass. |
| Software Management Plan/README.md | House-style edits and clarified documentation platform examples/link. |
| Repository Structure/README.md | Added REUSE/licensing artefacts and SECURITY/CITATION to suggested repo layouts; added explanatory paragraph. |
| Repository Structure/Example.md | Updated maturity badge link, added maturity disclaimer, and replaced “all rights reserved” with Apache+notice statement. |
| README.md | Reworked root contents list for consistency; added MARS section; consolidated top-level links. |
| Project Maturity/README.md | Restructured maturity guidance and provided a copy/paste badge+disclaimer template. |
| Principles/Open-Source-Principles.md | Refined security-scanning wording and fixed External Contributions link target. |
| Principles/Code-Of-Conduct.md | Standardised “Co-operating States” wording. |
| MARS language/MARS-Template.md | Fixed “Language” typo in template heading. |
| MARS language/MARS-007-Timespan-Absence.md | Fixed heading typo and removed an empty bullet. |
| MARS language/MARS-006-Land-Surface-Tile-Data.md | Normalised date format. |
| MARS language/MARS-005-CEMS-C3S-Hydrology.md | Corrected spelling/grammar in prose. |
| MARS language/MARS-004-land-data-assimilation-system.md | Corrected multiple typos and minor wording issues. |
| MARS language/MARS-003-model-errors-with-coeffs.md | Normalised status line formatting. |
| MARS language/MARS-002-flightLevels.md | House-style spelling fixes and corrected “non-existent”. |
| MARS language/MARS-001-MARS-Model-Keyword-for-DestinE-ODEDT.md | Normalised status/date formatting and added provenance note from ADR-006. |
| LICENSE | Populated root license with Apache 2.0 text plus ECMWF intergovernmental notice. |
| Legal/Requesting-New-Repository.md | Made open-sourcing link relative and added repo-structure/CLA guidance cross-links. |
| Legal/README.md | Clarified what the Apache-Licence file represents (template matching root LICENSE). |
| Legal/Open-Sourcing-Software.md | Clarified CLA Assistant instruction and linked to CLA document. |
| Legal/Copyright-And-Licensing.md | Rewrote Apache/NOTICE guidance for consistency; added EU/partner holder rules; added REUSE tooling guidance. |
| Legal/Apache-Licence | Replaced prior embedded copyright boilerplate with canonical Apache 2.0 text + ECMWF notice (matching root LICENSE). |
| Languages/README.md | Marked C++ and Versioning sections as WIP/placeholder to match actual content. |
| Languages/Python-Wheels.md | House-style spelling change (“customisable”). |
| Guidelines/README.md | Flagged Testing as draft/WIP and Observability as partially deferred. |
| Guidelines/Pull-Requests.md | Linked to Branching procedure (vs ADR rationale) and corrected typos. |
| Guidelines/Observability.md | House-style spelling updates and clarified deferred alerting spec note. |
| Guidelines/External-Contributions.md | Pointed “Fork” inheritance path to the standard forking procedure/template. |
| Guidelines/Containerisation.md | Renamed to British spelling throughout and updated TOC anchors accordingly. |
| Guidelines/Branching.md | Clarified ADR-001 vs procedure, normalised SemVer examples, and fixed tag example (1.9.0). |
| Guidelines/Ai-Contributions-To-Software.md | Added Agent Skills cross-link and tightened testing requirement wording for AI-generated code. |
| ESEE/README.md | Removed duplicate badge blocks and applied house-style spelling/wording updates. |
| Contributing Upstream/README.md | Expanded from single-line index to a short section intro plus contents. |
| Contributing Upstream/Forking.md | Clarified scope and linked relationship to External Contributions “Fork” option. |
| Agent Skills/README.md | Added policy linkage to AI contributions guidance and clarified “report/gate” behaviour. |
| ADR/README.md | Corrected ADR-005 title, ADR-007 status, and ADR-006 withdrawal reference to MARS-001. |
| ADR/ADR-Template.md | Normalised Status section layout/format. |
| ADR/ADR-Guidelines.md | Updated ADR index reference to ADR/README.md. |
| ADR/ADR-007-Approved-Dependency-libfmt.md | House-style spelling changes (“standardised”). |
| ADR/ADR-006-MARS-Model-Keyword-for-DestinE-ODEDT.md | Reduced to withdrawal stub pointing to MARS-001; normalised headings/dates. |
| ADR/ADR-005-Storing-Of-ICON-Grid-Files.md | Fixed ADR number in title and normalised status formatting. |
| ADR/ADR-004-Cascade-Features.md | Normalised status formatting and house-style spelling changes. |
| ADR/ADR-003-PyBind11-For-CPP-Bindings.md | Normalised status formatting. |
| ADR/ADR-002-Approved-Dependency-CLI11.md | Fixed heading formatting for Status section. |
| ADR/ADR-001-Git-Branching-Model.md | Normalised status formatting, added pointer to Branching procedure, and corrected typos. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Copyright-And-Licensing: 'If you are not familiar', 'Apache License', British 'licence header' / 'licence and liability disclaimer', drop 'please you may'. - Containerisation: 'one of the key foundations'; 'minimises'. - MARS-007: remove double period.
…Copilot) - MARS-001/003: keep the MARS series' bracketed [~~..~~] status convention (matching the MARS template and MARS-002/004-008); MARS-003 also converts <s> -> ~~. (ADR series remains bracketless.) - Open-Sourcing-Software: 'typically done', 'PRs'.
- Documentation-Publishing-On-Sites: version examples use the clean x.y.z form (5.2.0, 1.2.3, 2.1.0) to match the no-'v'-prefix tag convention; GitHub Action refs (@v4/@v5) and the sites api/v2 path are unchanged. - Pull-Requests: 'your PR's history'. - SMP: fix comma splice (semicolon).
- Open-Source-Principles: add 'and' to fix comma splice. - Agent Skills README: clarify NOT_READY = security-audit verdict (open CRITICAL/HIGH). - Pull-Requests: '(PRs)' to match plural usage.
- Repository Structure: setuptools' find_packages. - Agent Skills README: single space + reflow the security-audit note. - MARS-007: 'language semantics are updated'. - Open-Sourcing: 'the repository provides a PR template'.
…pilot) ESEE category badge hyperlinks now use tree/main/ESEE (the rendered directory) instead of the raw endpoint (which 404s for a directory); the badge .svg image srcs correctly stay on raw.
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
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
A cross-document consistency and clarity pass across the whole Codex, from a full read-only analysis (mechanical link/spelling/status checks + deep reads of every section). It fixes broken links, licensing contradictions, ADR status/formatting drift, section overlaps, rendering artefacts, and British house-style/typos — and marks advertised-but-empty sections as work-in-progress (their content is tracked in
TODO.md, not written here).44 files touched; 0 real broken internal links remain and all ADR index statuses now match their files.
What changed (by theme)
Broken links
Principles/Open-Source-Principles.md→Guidelines/External-Contributions.md;ADR/ADR-Guidelines.md→ the ADR index (README.md);Repository Structure/Example.mdmaturity badge →mainbranch/README.md;Requesting-New-Repository.mdmade relative.Licensing coherence
LICENSEwith the canonical form: Apache 2.0 text + ECMWF's intergovernmental notice at the tail; alignedLegal/Apache-Licenceto it and relabelled it accurately inLegal/README.md.Copyright-And-Licensing.md:NOTICEis never empty; removed the fragile "line 178" instruction; added the EU-funded ("European Union") and partner/Crown-Copyright holder rules; addedreuse annotatetooling; disambiguatedCONTRIBUTORSvsCONTRIBUTING.md; cleaned an empty heading + typos.Repository Structure/Example.md: replaced "© 2025 ECMWF. All rights reserved." with the mandated Apache licence block + maturity disclaimer.LICENSES/,NOTICE,REUSE.toml,SECURITY.md,CITATION.cff) to the Repository Structure layout trees.ADRs
[ ]brackets) and theADR-Template; fixed theADR-002heading; reduced ADR-006 to a withdrawal stub linking MARS-001 (with a reciprocal back-link).Skills ↔ policy
Ai-Contributions-To-Software.md↔Agent Skills; reconciled "mandatory security step" vs the advisory-when-not-yet-run rule; raised AI-generated-code testing to the same bar as all contributions; softened the "automated security scanning in CI" claim in the Principles.Branching & versioning
Branching.md= normative procedure (and pointed Pull-Requests at it); fixedv1.9.0→1.9.0andx.y.z+1→"next patch, e.g. 1.4.3→1.4.4"; cross-linked the canonical SemVer/tag conventions.Structure & overlaps
Rendering & house style
ESEEandProject Maturity(and normalised the maturity "copy this" blocks); British-spelling normalisation (Containerisation, Observability, SMP, ADR-004/007, ESEE, MARS-002); "Co-operating States"; MARS typos ("Languge"), an empty bullet, and strikethrough/date-format drift; assorted grammar fixes.WIP flagging —
Testing,Versioning,Languages/C++, and the Observability alerting section are now marked draft/WIP where their indexes over-promised;TODO.mdrefreshed to list the remaining content gaps.Notes for reviewers
TODO.md.LICENSEare the licence-block template snippets meant to be copied into a repo root (intentional).