docs: standardise repo structure and file naming conventions

ADR/ADR-008-Stack-Dependencies.md

@@ -250,7 +250,7 @@ via `add_subdirectory()`.
    In particular, the caching of build artifacts would have to be replicated everywhere
    potentially deteriorating the build time issue.
 
-6. The python_wheels documentation already identifies this approach as the
+6. The Python-Wheels documentation already identifies this approach as the
    intended path forward for compiled dependencies in wheel builds, indicating
    organisational alignment.
 
@@ -287,7 +287,7 @@ reviewable; the latter is opaque and unbounded.
   libfmt is managed by `stack-dependencies`. ADR-007 notes that libfmt is
   "trivially built from source with CMake" — `stack-dependencies` provides the
   `find_package(fmt)`-compatible install tree.
-- The python_wheels infrastructure (`Languages/python_wheels.md`) references
+- The Python-Wheels infrastructure (`Languages/Python-Wheels.md`) references
   this repository as the intended mechanism for external compiled dependencies
   in wheel builds.
 
@@ -312,7 +312,7 @@ provision them.
 - **Auditability**: the exact source of every dependency is available in the
   repository, satisfying compliance and licence audit requirements.
 - **Python wheel alignment**: unifies the dependency provisioning strategy
-  between the C++ build pipeline and the python_wheels pipeline.
+   between the C++ build pipeline and the Python-Wheels pipeline.
 
 ### Negative
 
@@ -330,7 +330,7 @@ provision them.
 ## References
 
 - `stack-dependencies` repository: https://github.com/ecmwf/stack-dependencies
-- Python wheels documentation: `Languages/python_wheels.md`
+- Python wheels documentation: `Languages/Python-Wheels.md`
 - ecbuild: https://github.com/ecmwf/ecbuild
 - Spack: https://spack.io/
 - Conan: https://conan.io/

ADR/ADR-Index.md → ADR/README.md

@@ -1,4 +1,13 @@
-# Architectural Decision Records (ADR) Index
+# Architectural Decision Records (ADR)
+
+Architectural Decision Records capturing key technical decisions for ECMWF software.
+
+## Resources
+
+- [ADR Guidelines](./ADR-Guidelines.md) — how to write and structure an ADR
+- [ADR Template](./ADR-Template.md) — blank template for new records
+
+## Index
 
 | ADR | Status |
 | ----------- | ----------- |

Contributing Upstream/README.md

@@ -1 +1 @@
-- [Forking External Repositories](./forking.md)
+- [Forking External Repositories](./Forking.md)

Guidelines/External-Contributions.md

@@ -19,8 +19,8 @@ Public contributions follow the normal GitHub workflow.
 - Develop on your fork.  
 - When ready, open a Pull Request (PR) to the ECMWF repository.  
 - Follow the repository’s PR template and provide sufficient description, issue references, and rationale.
-- Note that all contributions must comply with ECMWF’s copyright and licensing policies, as outlined in [Copyright and Licensing](../Legal/copyright_and_licensing.md).
-- By creating a PR, you agree to the terms of the [Contributor License Agreement (CLA)](../Legal/contributor_license_agreement.md) and this should be part of the PR template.
+- Note that all contributions must comply with ECMWF’s copyright and licensing policies, as outlined in [Copyright and Licensing](../Legal/Copyright-And-Licensing.md).
+- By creating a PR, you agree to the terms of the [Contributor License Agreement (CLA)](../Legal/Contributor-License-Agreement.md) and this should be part of the PR template.
 - ECMWF staff will review for safety and apply the label `approved-for-ci`, which enables automated CI/CD checks.  
 - The PR must pass all required tests, code-quality checks, and workflows before merge.  
 - All contributions must include tests demonstrating correct behaviour and preventing regressions.
@@ -35,17 +35,17 @@ For private repositories owned by ECMWF:
 - The project’s Technical Officer coordinates access requests.  
 - License management is handled by User Support (@bkasic).  
 - Development should occur on branches within the repository, using the same PR and review workflow as public repositories.
-- Even for an internal/private repository, by creating a PR, you agree to the terms of the [Contributor License Agreement (CLA)](../Legal/contributor_license_agreement.md) and this should be part of the PR template.
+- Even for an internal/private repository, by creating a PR, you agree to the terms of the [Contributor License Agreement (CLA)](../Legal/Contributor-License-Agreement.md) and this should be part of the PR template.
 
 ### New Repositories
 
 When a new repository is needed:
 
 - It must be created under the **ECMWF GitHub organisation**, not a personal or external account.  
-- Creation is handled by ECMWF staff via the Technical Officer, and must follow the [Requesting a New Repository](../Legal/requesting_new_repository.md) procedure.
+- Creation is handled by ECMWF staff via the Technical Officer, and must follow the [Requesting a New Repository](../Legal/Requesting-New-Repository.md) procedure.
 - Visibility (public or private) should be decided early, preferring public where feasible.
 - If the project will eventually be public, start development publicly to avoid migration overhead.
-- For public repositories or that eventually will be made public, all contributions must comply with ECMWF’s copyright and licensing policies, as outlined in [Copyright and Licensing](../Legal/copyright_and_licensing.md).
+- For public repositories or that eventually will be made public, all contributions must comply with ECMWF’s copyright and licensing policies, as outlined in [Copyright and Licensing](../Legal/Copyright-And-Licensing.md).
 - Initialise the repository using the ECMWF cookie-cutter template and follow the [Repository Structure](../Repository%20Structure/README.md).  
 - Add an appropriate [Project Maturity Badge](../Project%20Maturity/README.md) (e.g., *Sandbox*).
 - Ensure the PR template includes the CLA agreement, so that all contributors agree to it when submitting contributions.
@@ -57,14 +57,14 @@ If ECMWF inherits an external repository (e.g., a Code4Earth project), one of th
 1. **Recreate and Import** — create a new ECMWF repository using the cookie-cutter template, then import existing content via PR.  
 2. **Transfer Ownership** — transfer the repository into ECMWF’s organisation once it complies with ECMWF’s licensing, copyright, and workflow requirements. This must include:  
    - Adding the CLA agreement to the PR template.  
-   - Ensuring all past contributions comply with ECMWF’s [Copyright and Licensing](../Legal/copyright_and_licensing.md).  
-   - Ensuring the open sourcing guidelines in [Open Sourcing Software at ECMWF](../Legal/open_sourcing_software.md) are followed.
+   - Ensuring all past contributions comply with ECMWF’s [Copyright and Licensing](../Legal/Copyright-And-Licensing.md).  
+   - Ensuring the open sourcing guidelines in [Open Sourcing Software at ECMWF](../Legal/Open-Sourcing-Software.md) are followed.
 3. **Fork** — ECMWF forks the repository to maintain its own variant while the original remains active.  
    - Create an empty `default` branch containing a notice linking to the original project.  
    - Make `default` the default branch so that it shows as the main entrypoint to the repository.  
    - Disable all GitHub Actions to prevent execution of unverified workflows.
-   - Where applicable, ensure the forked repository complies with ECMWF’s [Copyright and Licensing](../Legal/copyright_and_licensing.md).
-   - Where applicable, ensure the open sourcing guidelines in [Open Sourcing Software at ECMWF](../Legal/open_sourcing_software.md) are followed.
+   - Where applicable, ensure the forked repository complies with ECMWF’s [Copyright and Licensing](../Legal/Copyright-And-Licensing.md).
+   - Where applicable, ensure the open sourcing guidelines in [Open Sourcing Software at ECMWF](../Legal/Open-Sourcing-Software.md) are followed.
 
 
 ---
@@ -116,7 +116,7 @@ When ready for delivery:
 
 1. Open a PR from the contractor’s fork `main` or from the ECMWF integration branch (`upstream` or `upstream/<vendor>`) into ECMWF’s `main` or `master`.  
 2. ECMWF staff perform review, validation, and compliance checks.  
-   - **Note:** at this stage, all contributions must comply with ECMWF’s copyright and licensing policies, as outlined in [Copyright and Licensing](../Legal/copyright_and_licensing.md) and for open source projects, the [Open Sourcing Software at ECMWF](../Legal/open_sourcing_software.md) guidelines.
+   - **Note:** at this stage, all contributions must comply with ECMWF’s copyright and licensing policies, as outlined in [Copyright and Licensing](../Legal/Copyright-And-Licensing.md) and for open source projects, the [Open Sourcing Software at ECMWF](../Legal/Open-Sourcing-Software.md) guidelines.
 
 3. Upon acceptance, ECMWF merges the PR. When appropriate, ECMWF can apply a **production tag**:
 

Languages/README.md

@@ -5,5 +5,5 @@ Language-specific guidelines and tooling for ECMWF software projects.
 ## Contents
 
 - [C++](./C++/README.md) — coding standards, clang-format and clang-tidy configuration
-- [Python Wheels](./python_wheels.md) — building and using Python wheels with compiled libraries
-- [Versioning](./versioning.md) — versioning guidance for multi-language repositories
+- [Python Wheels](./Python-Wheels.md) — building and using Python wheels with compiled libraries
+- [Versioning](./Versioning.md) — versioning guidance for multi-language repositories

Legal/copyright_and_licensing.md → Legal/Copyright-And-Licensing.md

@@ -17,7 +17,7 @@ In December 2011, it was decided that ECMWF software packages, when open sourced
         Copyright 1996- European Centre for Medium-Range Weather Forecasts (ECMWF)
 ```
 
-Alternatively, you can use the [apache-licence](apache-licence) file provided in this repository as a template.
+Alternatively, you can use the [Apache-Licence](Apache-Licence) file provided in this repository as a template.
 
 3. A correct `NOTICE` file **must** be included in the same directory as the `LICENSE` file and list ALL external code contributions (if any). Please follow the instructions the [Apache guidelines](http://www.apache.org/legal/src-headers.html#notice). Typically, the `NOTICE` file will be empty for ECMWF packages unless you have included third-party code.
 

Legal/open_sourcing_software.md → Legal/Open-Sourcing-Software.md

@@ -35,8 +35,8 @@ When open sourcing an ECMWF software, either as an ECMWF member or as a sub-cont
    - Use `.md` (prefered) or `.rst` format
 
 - Ensure the relevant software licence is applied
-   - One central licence file and references in each (code) file as described in [Copyright and Licensing](copyright_and_licensing.md)
-   - For Apache Licence, see [Applying the Apache License](copyright_and_licensing.md)
+   - One central licence file and references in each (code) file as described in [Copyright and Licensing](Copyright-And-Licensing.md)
+   - For Apache Licence, see [Applying the Apache License](Copyright-And-Licensing.md)
    - For first time releases, codes should be audited for:
       - IPR violations. Contact Development Section to arrange for a code audit
       - Sensitive information that is internal to ECMWF (e.g. passwords, user names, hostnames, emails, etc.)

Legal/README.md

@@ -0,0 +1,11 @@
+# Legal
+
+Legal guidance for ECMWF software projects covering licensing, copyright, and repository governance.
+
+## Contents
+
+- [Copyright and Licensing](./Copyright-And-Licensing.md) — ECMWF's approach to copyright and applying the Apache License
+- [Open Sourcing Software](./Open-Sourcing-Software.md) — checklist and guidelines for open sourcing ECMWF software
+- [Contributor Licence Agreement](./Contributor-License-Agreement.md) — CLA for contributions to ECMWF software
+- [Requesting a New Repository](./Requesting-New-Repository.md) — process for requesting or renaming GitHub repositories
+- [Apache Licence](./Apache-Licence) — full text of the Apache License 2.0

Legal/requesting_new_repository.md → Legal/Requesting-New-Repository.md

@@ -50,4 +50,4 @@ Requesting a **Public** repository (or changing an existing repository's visibil
 If your repository requires public visibility, you must complete the official open-sourcing approval procedure.
 Your repository will be first made Private and only made Public once the open-sourcing process is complete and approved.
 
-Please review and follow the guidelines documented here: [Open Sourcing Software Procedure](https://github.com/ecmwf/codex/blob/main/Legal/open_sourcing_software.md)
+Please review and follow the guidelines documented here: [Open Sourcing Software Procedure](https://github.com/ecmwf/codex/blob/main/Legal/Open-Sourcing-Software.md)

MARS language/MARS-Index.md → MARS language/README.md

@@ -1,4 +1,12 @@
-# MARS Language Decision Records Index
+# MARS Language Decision Records
+
+Decision records for changes and additions to the MARS language.
+
+## Resources
+
+- [MARS Template](./MARS-Template.md) — blank template for new MARS language records
+
+## Index
 
 | Item | Status |
 | -- | -- |

Principles/CODE_OF_CONDUCT.md → Principles/Code-Of-Conduct.md

@@ -4,7 +4,7 @@
 
 In developing software and services at ECMWF and with our community of Member and Cooperating States, we are
 committed to fostering an inclusive, respectful, and harassment-free community
-in line with [ECMWF's Open Source Principles](./open-source-principles.md),
+in line with [ECMWF's Open Source Principles](./Open-Source-Principles.md),
 which are inspired by the [United Nations Open Source Principles](https://opensource.un.org/en/news/united-nations-open-source-principles).
 
 In harmony with the [ECMWF's Charter of Ethics and Conduct](https://www.ecmwf.int/sites/default/files/Charter_of_Ethics.pdf),
@@ -64,4 +64,4 @@ to maintain confidentiality with regard to the reporter of an incident.
 This Code of Conduct is adapted from the
 [Contributor Covenant](https://www.contributor-covenant.org), version 2.1,
 available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html,
-and informed by [ECMWF's Open Source Principles](./open-source-principles.md).
+and informed by [ECMWF's Open Source Principles](./Open-Source-Principles.md).

Principles/README.md

@@ -0,0 +1,8 @@
+# Principles
+
+Core principles and standards guiding ECMWF software development.
+
+## Contents
+
+- [Open Source Principles](./Open-Source-Principles.md) — ECMWF's adoption of the United Nations Open Source Principles
+- [Code of Conduct](./Code-Of-Conduct.md) — standards of behaviour for ECMWF software development

README.md

@@ -10,7 +10,7 @@ The Codex is a set of principles and guidelines for development of software and
 
 # Contents
 
-- [Code of Conduct](./Principles/CODE_OF_CONDUCT.md)
+- [Code of Conduct](./Principles/Code-Of-Conduct.md)
 - [Principles](./Principles)
 - [Architectural Decision Records](./ADR)
 - [Repository Structure](./Repository%20Structure)

Software Management Plan/README.md

@@ -97,7 +97,7 @@ Optional:
 - **Template**
   - If using a repository template, please provide the link here.
 - **Licence**
-  - If not the standard [Apache 2.0 licence](../Legal/apache-licence)
+  - If not the standard [Apache 2.0 licence](../Legal/Apache-Licence)
 - **Long-term maintenance owner**
   - If this is not consistent across all repositories
 

TODO.md

@@ -8,8 +8,8 @@ Contributions addressing any of these items are welcome via pull request.
 ## High Priority
 
 - [ ] **Guidelines/Testing.md** — File opens with an explicit `TODO`. No actual testing guidelines exist beyond test data hosting via `sites.ecmwf.int`. Needs unit, integration, and regression testing standards.
-- [ ] **Languages/versioning.md** — Entire file is a single-line placeholder: *"How do we manage multi-language repositories with a single version number?"*. Needs a versioning policy.
-- [ ] **LICENSE** (root) — File is empty. The licence text exists in `Legal/apache-licence` but the root `LICENSE` file that GitHub uses for badge detection and display contains no content.
+- [ ] **Languages/Versioning.md** — Entire file is a single-line placeholder: *"How do we manage multi-language repositories with a single version number?"*. Needs a versioning policy.
+- [ ] **LICENSE** (root) — File is empty. The licence text exists in `Legal/Apache-Licence` but the root `LICENSE` file that GitHub uses for badge detection and display contains no content.
 
 ## Medium Priority
 
@@ -24,5 +24,5 @@ Contributions addressing any of these items are welcome via pull request.
 - [ ] **MARS language/MARS-Template.md** — Typo in title: "Languge" should be "Language".
 - [ ] **MARS language/MARS-007-Timespan-Absence.md** — Same "Languge" typo in title. Also contains an empty bullet point (`* `) around line 200.
 - [ ] **Contributing Upstream/README.md** — Single-line index file. Could benefit from a brief introductory paragraph explaining the purpose of the section.
-- [ ] **Repository Structure/example.md** — Only provides a Python project README template. No equivalent example for a C++ project.
-- [ ] **Languages/python_wheels.md** — Notes that automated release triggering is pending and pin derivation for Python interface wheels has a known deficiency.
+- [ ] **Repository Structure/Example.md** — Only provides a Python project README template. No equivalent example for a C++ project.
+- [ ] **Languages/Python-Wheels.md** — Notes that automated release triggering is pending and pin derivation for Python interface wheels has a known deficiency.