ecmwf · jameshawkes · Nov 5, 2025 · Sep 30, 2025 · Sep 30, 2025 · Oct 15, 2025
diff --git a/External Contributions/README.md b/External Contributions/README.md
@@ -0,0 +1,123 @@
+# External Contributions
+
+These guidelines define how all external contributions to the ECMWF software stack must be developed, delivered, and maintained. They apply to all collaborators, including individuals, partner organisations, and contracted suppliers, across all ECMWF-managed repositories (software, configuration, deployment manifests, and scripts).
+
+Two contribution pathways exist, depending on the nature of the work:
+
+1. **Standard Contributions** — the default method for all collaborators, using a fork and pull request workflow.  
+2. **Integration Delivery Workflow** — an optional process for contractors who require tighter integration loops or internal tagging for staged testing prior to formal ECMWF review.
+
+---
+
+## 1. Standard Contributions (Default Method)
+
+### Public Repositories
+
+Public contributions follow the normal GitHub workflow.
+
+- Fork the ECMWF repository into your own or your organisation’s GitHub space.  
+- 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.  
+- 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.
+
+This process applies equally to **contractors** unless following the Integration Delivery Workflow (Section 2).
+
+### Private Repositories
+
+For private repositories owned by ECMWF:
+
+- Access requires an ECMWF GitHub Enterprise license.  
+- 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.
+
+### 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.  
+- 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.  
+- 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*).
+
+### Existing Repositories
+
+If ECMWF inherits an external repository (e.g., a Code4Earth project), one of three paths is used:
+
+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.  
+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.
+
+---
+
+## 2. Integration Delivery Workflow (Optional)
+
+This workflow is **only** for external contractors who need a tighter development loop, internal tagging, or pre-delivery staging. It defines a controlled structure for interim releases before formal ECMWF acceptance. This should be used, for example, for systems or services which will be deployed (in a test or development environment ONLY) as part of the testing and acceptance process.
+
+### Development and Branch Model
+
+Contractors may work in one of two ways:
+
+1. **Forked Development** — using the contractor’s fork of the ECMWF repository.  
+   - The fork’s `main` branch serves as the contractor’s working “upstream” branch.  
+   - Tags and iterations remain isolated to the contractor’s fork.
+
+2. **ECMWF Integration Branch** — when working directly in the ECMWF repository.  
+   - The contractor creates their own integration branch named `upstream` or namespaced as `upstream/<vendor>`.
+   - Direct commits to ECMWF’s `main` or `master` are not permitted.  
+   - Force-pushes are prohibited.  
+   - All changes are proposed to ECMWF `main` or `master` via Pull Requests from the integration branch.
+
+### Tagging Rules
+
+Contractors using this model may create prerelease tags for internal testing and staging:
+
+```
+x.y.z-upstream.N
+```
+
+
+Where:  
+- `x.y.z` = semantic version (major.minor.patch), which is the target release version upon acceptance
+- `N` = sequential prerelease number (1, 2, 3, …)
+
+Rules:
+- These prerelease tags are **non-production**.  
+- They must not appear on ECMWF’s `main` or `master` branches.  
+- They are valid only for contractor-side testing, packaging, or CI pipelines.  
+- ECMWF production tags must use the clean SemVer form:
+
+```
+x.y.z
+```
+
+### Submission and Approval
+
+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.  
+3. Upon acceptance, ECMWF merges the PR. When appropriate, ECMWF can apply a **production tag**:
+
+```
+x.y.z
+```
+
+Acceptance of the PR is the point at which a contractor's deliverable is accepted for the purposes of the contract.
+
+Only a production tag marks the release as production-ready.
+
+### Production Control
+
+- Upstream tags are explicitly **non-production**.  
+- Only clean ECMWF-issued tags (`x.y.z`) on `main` or `master` represent production software.  
+- Non-production tags must never be deployed beyond development or test environments.
+
diff --git a/README.md b/README.md
@@ -15,3 +15,4 @@ The Codex is a set of guidelines for development of software and services at ECM
 - [Project Maturity](./Project%20Maturity)
 - [Containerisation](./Containerisation)
 - [ECMWF Software EnginE (ESEE)](./ESEE)
+- [External Contributions](./External%20Contributions/)
diff --git a/Repository Structure/README.md b/Repository Structure/README.md
@@ -1,18 +1,19 @@
 # Repository Structure
 
-These are the guidelines for how to set up a repository...
-
-To get started you can [use the cookiecutter template](https://github.com/ecmwf/cookie-cutter).
-
-- [Readme](#Readme)
-- [Badges](#Badges)
-- [Code Structure](#code-structure)
+These are the guidelines for how a software package repository should be structured.
+If creating a new software package repository you should
+[use the cookiecutter template](https://github.com/ecmwf/cookie-cutter) which will create
+respository following the guidelines documented below.
+
+- [Repository Structure](#repository-structure)
+  - [Readme](#readme)
+  - [Badges](#badges)
+  - [Code Structure](#code-structure)
     - [Python](#python)
-    - [C++](#c++)
-    - [Rust](#Rust)
-    - [Mixed Languages](#mixed-languages)
-- [License](#License)
-- [Contributors](#Contributors)
+    - [C/C++](#cc)
+  - [License](#license)
+  - [Contributors](#contributors)
+  - [Resources](#resources)
 
 ## Readme
 Each repository must contain a README.md file. The cookiecutter generates one automatically from a template file. The generated README.md must then be filled in with project specific information.
@@ -71,14 +72,6 @@ Note the extra src directory. This prevents setuptool's find_package from adding
     └── test_N
 ```
 
-
-### Rust
-TODO
-
-### Mixed Languages
-
-
-
 ## License
 Add a LICENSE file at the root of the project. Add following text to the README.md file:
 
@@ -90,47 +83,6 @@ Add a LICENSE file at the root of the project. Add following text to the README.
 ## Contributors
 The cookiecutter template automatically generates a contributors file. External contributors are encouraged to open their Pull Requests to be added to the list.
 
+## Resources
 
-A [Cookiecutter] template for an ECMWF project.
-
-# Using the Template
-
-Generate the project skeleton in a new directory:
-
-    cookiecutter ssh://git@github.com:ecmwf/cookie-cutter.git
-
-For adding readmes and files to existing projects, make sure to supply an additional parameter to overwrite existing directories:
-
-    cookiecutter ssh://git@github.com:ecmwf/cookie-cutter.git --overwrite-if-exists
-
-You will be asked to provide answers to several questions, in order to properly prepare the template for you. In case you don't know the answer, you can just leave the answer at the default value by pressing Enter.
-
-Note that several features are optional, you can activate them by answering 'y' when prompted.
-
-## Glossary
-
-* `project_name`: Official name of the project, used as input for project_slug
-* `project_slug`: Used as name of the project directory, alphanumerics only
-* `project_description`: Textual description of the project
-* `maturity_badge`: Level of maturity of the repository
-* `docs_dir`: Subdirectory for the documentation, supply a dot (.) for none
-* `copyright_year`: Official start year of copyright
-* `copyright_name`: Official copyright holder name
-* `github_organisation`: Github space where the repository lives
-* `language`: The main language of the repository, used for structure and guidelines generation
-* `fail_on_warning`: Fail build when warning is encountered
-* `additional_formats`: Whether to generate PDF/EPUB/single HTML formats for the docs
-* `use_github_workflow`: Whether to add Github workflow to test doc builds
-* `use_include`: Whether to include upper directories in documentation
-* `use_autodoc`: Whether to document Python code automatically
-* `use_version_file`: Whether to infer release version from VERSION file
-* `use_doxygen`: Whether to document C/C++ code automatically
-* `use_ipynb`: Whether to add support for Jupyter Notebooks
-* `use_copybutton`: Whether to add copy to clipboard button for code blocks
-* `use_tabs`: Whether to add tabs for switchable content
-* `use_todo`: Whether to add TODO comment blocks
-* `use_fortran`: Whether to add support for documenting Fortran code
-* `use_ecflow_lexer`: Whether to add support for ecFlow syntax highlighting
-* `open_source_license`: Project licence
-* `logo_path_light`: Filepath to a logo for light mode, skipped if not provided
-* `logo_path_dark`: Filepath to a logo for dark mode, use light if not provided
+- [Cookiecutter template](https://github.com/ecmwf/cookie-cutter)