From 9a8f7da91774ca88458e8588337ffb13823c05d7 Mon Sep 17 00:00:00 2001 From: James Varndell Date: Mon, 22 Jun 2026 09:21:32 +0100 Subject: [PATCH 01/12] Adds draft software delivery documentation --- Software Delivery/Technical-Handover.md | 57 +++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 Software Delivery/Technical-Handover.md diff --git a/Software Delivery/Technical-Handover.md b/Software Delivery/Technical-Handover.md new file mode 100644 index 0000000..9b4cf24 --- /dev/null +++ b/Software Delivery/Technical-Handover.md @@ -0,0 +1,57 @@ +# Technical Handover Documentation + +These guidelines define what a contractor must deliver when handing over a web product (or other software service) to ECMWF. They apply to all external suppliers delivering software under Copernicus and other ECMWF contracts where ECMWF will assume ownership and operation of the delivered software. + +The purpose of the handover is to allow an ECMWF team with no prior involvement in the project to take full ownership of the software: to hold and maintain all source code, to deploy and operate every component on ECMWF infrastructure, and to understand every external dependency required to run it. These requirements complement, and do not replace, the [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) guidelines, which govern how code is contributed and delivered. + +Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a technical handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. + +--- + +## 1. Code Delivery + +All source code must be delivered to ECMWF as one or more **GitHub repositories within the ECMWF GitHub organisation**. Code is not considered delivered if it resides only in a personal account, an organisation's own GitHub space, or any location outside ECMWF's organisation. + +* Repositories are created by ECMWF staff via the Technical Officer, following the [Requesting a New Repository](https://github.com/ecmwf/codex/blob/main/Legal/Requesting-New-Repository.md) procedure. +* To enable ECMWF to create the repositories, the contractor must provide: + * the **number of repositories** required; + * the **name of each repository**, with a brief description of its contents; + * the **GitHub user accounts** that require access, and for each, the corresponding **ECMWF account username**. Every contributor who requires access must hold *both* a GitHub account and an ECMWF account; access cannot be granted without both. +* All code contributions must follow the workflow, copyright, and licensing requirements set out in [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) and [Copyright and Licensing](https://github.com/ecmwf/codex/blob/main/Legal/Copyright-And-Licensing.md). +* Each repository must contain a `README` describing its contents and providing instructions for building and running the component locally. + +## 2. Deployment on ECMWF Infrastructure + +ECMWF must be able to deploy and operate every delivered component on its **own infrastructure**, independently of any environment maintained by the contractor. ECMWF will not assume responsibility for, or continue to use, contractor-hosted infrastructure. + +* **Docker** is the required containerisation method. Every component that is containerised must be delivered with its **Dockerfile(s)** and documentation explaining how the containerisation works — what each image contains, how images are built, and how they are run. +* **Helm** and **Kubernetes** are the tools ECMWF uses to deploy applications. For simple applications, the Docker files alone are often sufficient for ECMWF to deploy the component on its own infrastructure. Where the contractor uses a more complex deployment process — for example, separately deployed backend and frontend components — the contractor must provide the **Helm and Kubernetes configuration** they use to deploy these, so that ECMWF can reproduce the deployment. +* Deployment recipes must be accompanied by **detailed, step-by-step instructions** sufficient for ECMWF to deploy the software from scratch on its own cluster, without reference to, or dependency on, the contractor's environment. +* Instructions must cover deploying a change, deploying from scratch, and rolling back a deployment. +* Any configuration that differs between environments (e.g. development, staging, production) must be documented, along with every environment variable, secret, and configuration value ECMWF must supply. +* Any value, endpoint, or credential currently hardcoded or otherwise bound to the contractor's infrastructure must be clearly identified, with guidance on what ECMWF must change. + +## 3. Source Code + +* Each repository's README must list every repository delivered for the project (e.g. frontend, backend, infrastructure, data pipelines), matching the repository names provided under Section 1, with a one-line description of each, and link to the others. +* For each repository, the README must state the main branch, any branching conventions in use, and the location of build-and-run instructions. + +## 4. Data + +* The README must describe how the data behind the application was generated or sourced, including original sources and any scripts or pipelines used to produce it. +* It must explain how ECMWF would regenerate or refresh the data itself, identifying the repository in which the relevant scripts reside and any manual steps involved. + +## 5. Supporting Services + +* The README must list every external service required to run the application, including but not limited to databases, object storage (e.g. S3 buckets), caches, queues, authentication providers, and monitoring. +* For each service, the README must state its purpose, its configuration, and what ECMWF must provision on its own infrastructure to replace any instance currently running in the contractor's environment. For databases, this includes type, version, schema, and connection details. + +## 6. Licences and Third-Party Services + +* The README must list every commercial licence, paid API, or subscription required to run the application — for example, a Mapbox licence for mapping. +* For each, it must state its purpose, where the corresponding API keys or credentials are configured, and what ECMWF must establish under its own accounts. Anything currently bound to the contractor's accounts must be flagged. + +## 7. Access, Credentials, and Configuration + +* The README must summarise all secrets, keys, and configuration values required to run the application, and state where each should reside (e.g. Kubernetes secrets, environment variables). +* Any credential bound to the contractor's personal or organisational accounts must be flagged as requiring replacement rather than transfer. \ No newline at end of file From a9b0e81b5f64feb54c83927d1ca5f32475877a47 Mon Sep 17 00:00:00 2001 From: James Varndell <36902610+JamesVarndell@users.noreply.github.com> Date: Mon, 22 Jun 2026 11:51:03 +0100 Subject: [PATCH 02/12] Update Software Delivery/Technical-Handover.md Co-authored-by: Eddy Comyn-Platt <53045993+EddyCMWF@users.noreply.github.com> --- Software Delivery/Technical-Handover.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Software Delivery/Technical-Handover.md b/Software Delivery/Technical-Handover.md index 9b4cf24..367b636 100644 --- a/Software Delivery/Technical-Handover.md +++ b/Software Delivery/Technical-Handover.md @@ -1,6 +1,6 @@ # Technical Handover Documentation -These guidelines define what a contractor must deliver when handing over a web product (or other software service) to ECMWF. They apply to all external suppliers delivering software under Copernicus and other ECMWF contracts where ECMWF will assume ownership and operation of the delivered software. +These guidelines define what a contractor must deliver when handing over a software service and/or product (e.g. a web application or a data production workflow) to ECMWF. They apply to all external suppliers delivering software under Copernicus and other ECMWF contracts where ECMWF will assume ownership and operation of the delivered software. The purpose of the handover is to allow an ECMWF team with no prior involvement in the project to take full ownership of the software: to hold and maintain all source code, to deploy and operate every component on ECMWF infrastructure, and to understand every external dependency required to run it. These requirements complement, and do not replace, the [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) guidelines, which govern how code is contributed and delivered. From 584d31c4a290c81017c7921d81b57202db8b88a4 Mon Sep 17 00:00:00 2001 From: James Varndell Date: Mon, 22 Jun 2026 11:54:12 +0100 Subject: [PATCH 03/12] References SMP instead of re-implementing new repo instructions --- Software Delivery/Technical-Handover.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/Software Delivery/Technical-Handover.md b/Software Delivery/Technical-Handover.md index 9b4cf24..fe7ae4e 100644 --- a/Software Delivery/Technical-Handover.md +++ b/Software Delivery/Technical-Handover.md @@ -13,11 +13,7 @@ Documentation must live with the code. The information described in these guidel All source code must be delivered to ECMWF as one or more **GitHub repositories within the ECMWF GitHub organisation**. Code is not considered delivered if it resides only in a personal account, an organisation's own GitHub space, or any location outside ECMWF's organisation. * Repositories are created by ECMWF staff via the Technical Officer, following the [Requesting a New Repository](https://github.com/ecmwf/codex/blob/main/Legal/Requesting-New-Repository.md) procedure. -* To enable ECMWF to create the repositories, the contractor must provide: - * the **number of repositories** required; - * the **name of each repository**, with a brief description of its contents; - * the **GitHub user accounts** that require access, and for each, the corresponding **ECMWF account username**. Every contributor who requires access must hold *both* a GitHub account and an ECMWF account; access cannot be granted without both. -* All code contributions must follow the workflow, copyright, and licensing requirements set out in [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) and [Copyright and Licensing](https://github.com/ecmwf/codex/blob/main/Legal/Copyright-And-Licensing.md). +* To enable ECMWF to create the repositories, the contractor must provide all of the information required as described in the [Software Management Plan](https://github.com/ecmwf/codex/tree/main/Software%20Management%20Plan#5-new-repositories) guidelines. * Each repository must contain a `README` describing its contents and providing instructions for building and running the component locally. ## 2. Deployment on ECMWF Infrastructure From ac080bfc11493c132c3844192ace2449b352fece Mon Sep 17 00:00:00 2001 From: mattofficeuk <39481661+mattofficeuk@users.noreply.github.com> Date: Mon, 22 Jun 2026 12:01:33 +0100 Subject: [PATCH 04/12] Clarify AI tools responsibility in documentation Added a note on the use of AI tools for documentation. --- Software Delivery/Technical-Handover.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Software Delivery/Technical-Handover.md b/Software Delivery/Technical-Handover.md index bb2d80b..701916f 100644 --- a/Software Delivery/Technical-Handover.md +++ b/Software Delivery/Technical-Handover.md @@ -6,6 +6,8 @@ The purpose of the handover is to allow an ECMWF team with no prior involvement Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a technical handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. +AI tools may be used to assist in writing this documentation, but the contractor is responsible for, and must ensure, the final completeness and correctness. + --- ## 1. Code Delivery @@ -50,4 +52,4 @@ ECMWF must be able to deploy and operate every delivered component on its **own ## 7. Access, Credentials, and Configuration * The README must summarise all secrets, keys, and configuration values required to run the application, and state where each should reside (e.g. Kubernetes secrets, environment variables). -* Any credential bound to the contractor's personal or organisational accounts must be flagged as requiring replacement rather than transfer. \ No newline at end of file +* Any credential bound to the contractor's personal or organisational accounts must be flagged as requiring replacement rather than transfer. From 3c22770081058bf54cea05d25fef211a56b403b9 Mon Sep 17 00:00:00 2001 From: James Varndell Date: Mon, 22 Jun 2026 12:51:59 +0100 Subject: [PATCH 05/12] Adds statement on AI use for documentation --- Software Delivery/Technical-Handover.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Software Delivery/Technical-Handover.md b/Software Delivery/Technical-Handover.md index bb2d80b..aaf00f5 100644 --- a/Software Delivery/Technical-Handover.md +++ b/Software Delivery/Technical-Handover.md @@ -4,7 +4,7 @@ These guidelines define what a contractor must deliver when handing over a softw The purpose of the handover is to allow an ECMWF team with no prior involvement in the project to take full ownership of the software: to hold and maintain all source code, to deploy and operate every component on ECMWF infrastructure, and to understand every external dependency required to run it. These requirements complement, and do not replace, the [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) guidelines, which govern how code is contributed and delivered. -Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a technical handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. +Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a technical handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. AI tools may be used to assist in writing this documentation, but the contractor is responsible for, and must ensure, the final completeness and correctness. --- From 68d3c818ca303752ca44d425250acd63cb3f9460 Mon Sep 17 00:00:00 2001 From: James Varndell <36902610+JamesVarndell@users.noreply.github.com> Date: Tue, 30 Jun 2026 14:43:54 +0100 Subject: [PATCH 06/12] Eliminate duplicate documentation guidelines Removed duplicate paragraph about documentation requirements. --- Software Delivery/Technical-Handover.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Software Delivery/Technical-Handover.md b/Software Delivery/Technical-Handover.md index cc5f143..701916f 100644 --- a/Software Delivery/Technical-Handover.md +++ b/Software Delivery/Technical-Handover.md @@ -4,7 +4,7 @@ These guidelines define what a contractor must deliver when handing over a softw The purpose of the handover is to allow an ECMWF team with no prior involvement in the project to take full ownership of the software: to hold and maintain all source code, to deploy and operate every component on ECMWF infrastructure, and to understand every external dependency required to run it. These requirements complement, and do not replace, the [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) guidelines, which govern how code is contributed and delivered. -Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a technical handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. AI tools may be used to assist in writing this documentation, but the contractor is responsible for, and must ensure, the final completeness and correctness. +Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a technical handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. AI tools may be used to assist in writing this documentation, but the contractor is responsible for, and must ensure, the final completeness and correctness. From 29210db14379c65edcc19f0b0354ba8dea514ecb Mon Sep 17 00:00:00 2001 From: James Varndell Date: Mon, 6 Jul 2026 17:26:49 +0100 Subject: [PATCH 07/12] Addressing feedback --- Software Delivery/Technical-Handover.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/Software Delivery/Technical-Handover.md b/Software Delivery/Technical-Handover.md index aaf00f5..24b030e 100644 --- a/Software Delivery/Technical-Handover.md +++ b/Software Delivery/Technical-Handover.md @@ -1,18 +1,22 @@ -# Technical Handover Documentation +# Continuous Web Application Delivery to ECMWF -These guidelines define what a contractor must deliver when handing over a software service and/or product (e.g. a web application or a data production workflow) to ECMWF. They apply to all external suppliers delivering software under Copernicus and other ECMWF contracts where ECMWF will assume ownership and operation of the delivered software. +These guidelines define what a contractor must deliver so that ECMWF can assume ownership and operation of a software service and/or product (e.g. a web application or a data production workflow). They apply to all external suppliers delivering software under Copernicus and other ECMWF contracts where ECMWF will assume ownership and operation of the delivered software. -The purpose of the handover is to allow an ECMWF team with no prior involvement in the project to take full ownership of the software: to hold and maintain all source code, to deploy and operate every component on ECMWF infrastructure, and to understand every external dependency required to run it. These requirements complement, and do not replace, the [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) guidelines, which govern how code is contributed and delivered. +Delivery to ECMWF is a **continuous process, not a one-off event at the end of a project**. ECMWF repositories must be requested and set up at the **beginning** of a project, and code, documentation, and deployment recipes must be delivered into them incrementally throughout the work. Treating delivery as a final "handover" step risks lost history, undocumented decisions, and code that cannot be built or operated by anyone other than the contractor. Working continuously in the ECMWF organisation from the outset avoids this and keeps the software in a deliverable state at all times. -Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a technical handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. AI tools may be used to assist in writing this documentation, but the contractor is responsible for, and must ensure, the final completeness and correctness. +The goal is that an ECMWF team with no prior involvement in the project can take full ownership of the software at any point: hold and maintain all source code, deploy and operate every component on ECMWF infrastructure, and understand every external dependency required to run it. These requirements complement, and do not replace, the [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) guidelines, which govern how code is contributed and delivered. + +**Technology choices require pre-agreement with ECMWF.** The technologies, languages, frameworks, and third-party services used in the delivered application — including those used to author and publish its documentation — must be agreed with ECMWF in advance, before development begins. This ensures that ECMWF can build, operate, and maintain the software and its documentation with its own teams and tooling once delivered. Contractors must not introduce technologies that ECMWF has not approved without first agreeing them with the Technical Officer. + +Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a formal delivery or handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. AI tools may be used to assist in writing this documentation, but the contractor is responsible for, and must ensure, the final completeness and correctness. --- ## 1. Code Delivery -All source code must be delivered to ECMWF as one or more **GitHub repositories within the ECMWF GitHub organisation**. Code is not considered delivered if it resides only in a personal account, an organisation's own GitHub space, or any location outside ECMWF's organisation. +All source code must be delivered to ECMWF as one or more **GitHub repositories within the ECMWF GitHub organisation**. Code is not considered delivered if it resides only in a personal account, an organisation's own GitHub space, or any location outside ECMWF's organisation. These repositories must be created at the **start** of the project and used as the primary home for the code throughout, not populated only at its end. -* Repositories are created by ECMWF staff via the Technical Officer, following the [Requesting a New Repository](https://github.com/ecmwf/codex/blob/main/Legal/Requesting-New-Repository.md) procedure. +* Repositories are created by ECMWF staff via the Technical Officer, following the [Requesting a New Repository](https://github.com/ecmwf/codex/blob/main/Legal/Requesting-New-Repository.md) procedure, and should be requested as early as possible so that development happens in the ECMWF organisation from the outset. * To enable ECMWF to create the repositories, the contractor must provide all of the information required as described in the [Software Management Plan](https://github.com/ecmwf/codex/tree/main/Software%20Management%20Plan#5-new-repositories) guidelines. * Each repository must contain a `README` describing its contents and providing instructions for building and running the component locally. @@ -50,4 +54,5 @@ ECMWF must be able to deploy and operate every delivered component on its **own ## 7. Access, Credentials, and Configuration * The README must summarise all secrets, keys, and configuration values required to run the application, and state where each should reside (e.g. Kubernetes secrets, environment variables). -* Any credential bound to the contractor's personal or organisational accounts must be flagged as requiring replacement rather than transfer. \ No newline at end of file +* For every secret, key, or credential that can or must be re-generated (e.g. API keys, signing keys, tokens, database passwords, TLS certificates), the README must document **how ECMWF regenerates it** — the service or tool used, the exact steps to follow, and where the new value must then be configured for the application to keep working. +* Any credential bound to the contractor's personal or organisational accounts must be flagged as requiring replacement rather than transfer, with instructions for generating an equivalent value under ECMWF's own accounts. \ No newline at end of file From 1db7415540d713c27f9f2c76c70856acf4944108 Mon Sep 17 00:00:00 2001 From: Tiago Quintino Date: Wed, 8 Jul 2026 21:23:08 +0100 Subject: [PATCH 08/12] Rework software delivery doc: move to Guidelines, broaden scope, wire cross-links - Move 'Software Delivery/Technical-Handover.md' -> 'Guidelines/Continuous- Software-Delivery.md'; retitle 'Continuous Software Delivery to ECMWF' (scope is software, not only web apps). Index in Guidelines/README.md and root README. - Apply reviewer suggestions: emphasis-flipped intro (EddyCMWF); deployment architecture must be agreed with the Technical Officer (Docker/Helm/K8s are the default, not a hard requirement, so data-production workflows fit); recommend multi-container deployment config in a separate repository. - Convert absolute GitHub URLs to relative links. - Align with current Codex: licensing (Apache-2.0 + SPDX/REUSE per ADR-010), Repository Structure conventions (incl. SECURITY.md), never-commit-secrets (history scanned before publication), AI-Contributions link, and a Publication/open-sourcing paragraph (repos start private; publication via Open-Sourcing-Software + audit gates). - Bidirectional linkage with External-Contributions (which governs *how* code flows; PR-into-main is the contractual acceptance point) + reverse pointer. --- .../Continuous-Software-Delivery.md | 25 +++++++++++++------ Guidelines/External-Contributions.md | 2 ++ Guidelines/README.md | 1 + README.md | 1 + 4 files changed, 21 insertions(+), 8 deletions(-) rename Software Delivery/Technical-Handover.md => Guidelines/Continuous-Software-Delivery.md (64%) diff --git a/Software Delivery/Technical-Handover.md b/Guidelines/Continuous-Software-Delivery.md similarity index 64% rename from Software Delivery/Technical-Handover.md rename to Guidelines/Continuous-Software-Delivery.md index d38fbfa..7676c2f 100644 --- a/Software Delivery/Technical-Handover.md +++ b/Guidelines/Continuous-Software-Delivery.md @@ -1,16 +1,16 @@ -# Continuous Web Application Delivery to ECMWF +# Continuous Software Delivery to ECMWF -These guidelines define what a contractor must deliver so that ECMWF can assume ownership and operation of a software service and/or product (e.g. a web application or a data production workflow). They apply to all external suppliers delivering software under Copernicus and other ECMWF contracts where ECMWF will assume ownership and operation of the delivered software. +These guidelines define what a contractor must deliver when handing over a software service and/or product (e.g. a web application or a data production workflow) to ECMWF. They apply to all external suppliers delivering software under Copernicus and other ECMWF contracts where ECMWF will assume ownership and operation of the delivered software. Delivery to ECMWF is a **continuous process, not a one-off event at the end of a project**. ECMWF repositories must be requested and set up at the **beginning** of a project, and code, documentation, and deployment recipes must be delivered into them incrementally throughout the work. Treating delivery as a final "handover" step risks lost history, undocumented decisions, and code that cannot be built or operated by anyone other than the contractor. Working continuously in the ECMWF organisation from the outset avoids this and keeps the software in a deliverable state at all times. -The goal is that an ECMWF team with no prior involvement in the project can take full ownership of the software at any point: hold and maintain all source code, deploy and operate every component on ECMWF infrastructure, and understand every external dependency required to run it. These requirements complement, and do not replace, the [External Contributions](https://github.com/ecmwf/codex/blob/main/Guidelines/External-Contributions.md) guidelines, which govern how code is contributed and delivered. +The goal is that an ECMWF team with no prior involvement in the project can take full ownership of the software at any point: hold and maintain all source code, deploy and operate every component on ECMWF infrastructure, and understand every external dependency required to run it. These requirements complement, and do not replace, the [External Contributions](./External-Contributions.md) guidelines, which govern *how* code is contributed and delivered — via the standard fork-and-pull-request workflow or, for contractors needing staged testing, the **Integration Delivery Workflow** (with `x.y.z-upstream.N` prerelease tags). Under those guidelines, **acceptance of a pull request into `main` is the point at which a deliverable is accepted for the contract**; delivering continuously into ECMWF repositories from the outset is what keeps that possible at any time, rather than only at the end. **Technology choices require pre-agreement with ECMWF.** The technologies, languages, frameworks, and third-party services used in the delivered application — including those used to author and publish its documentation — must be agreed with ECMWF in advance, before development begins. This ensures that ECMWF can build, operate, and maintain the software and its documentation with its own teams and tooling once delivered. Contractors must not introduce technologies that ECMWF has not approved without first agreeing them with the Technical Officer. Documentation must live with the code. The information described in these guidelines must be recorded in the **README** of the relevant repository, or in documentation linked directly from it, rather than collected in a standalone document that can become detached from the code and lost. Where a project spans several repositories, each repository's README must link to the others, so that the full set can be navigated from any one of them. Where a formal delivery or handover document is required as a contract deliverable, it need not duplicate this material — it may cross-reference the relevant repository documentation. -AI tools may be used to assist in writing this documentation, but the contractor is responsible for, and must ensure, the final completeness and correctness. +AI tools may be used to assist in writing this documentation — and, subject to the [AI Contributions to Software](./Ai-Contributions-To-Software.md) guidelines, in producing the code itself — but the contractor is responsible for, and must ensure, the final completeness and correctness. --- @@ -18,16 +18,20 @@ AI tools may be used to assist in writing this documentation, but the contractor All source code must be delivered to ECMWF as one or more **GitHub repositories within the ECMWF GitHub organisation**. Code is not considered delivered if it resides only in a personal account, an organisation's own GitHub space, or any location outside ECMWF's organisation. These repositories must be created at the **start** of the project and used as the primary home for the code throughout, not populated only at its end. -* Repositories are created by ECMWF staff via the Technical Officer, following the [Requesting a New Repository](https://github.com/ecmwf/codex/blob/main/Legal/Requesting-New-Repository.md) procedure, and should be requested as early as possible so that development happens in the ECMWF organisation from the outset. -* To enable ECMWF to create the repositories, the contractor must provide all of the information required as described in the [Software Management Plan](https://github.com/ecmwf/codex/tree/main/Software%20Management%20Plan#5-new-repositories) guidelines. +* Repositories are created by ECMWF staff via the Technical Officer, following the [Requesting a New Repository](../Legal/Requesting-New-Repository.md) procedure, and should be requested as early as possible so that development happens in the ECMWF organisation from the outset. +* To enable ECMWF to create the repositories, the contractor must provide all of the information required as described in the [Software Management Plan](../Software%20Management%20Plan/README.md#5-new-repositories) guidelines. +* Each repository is initialised using the ECMWF cookie-cutter template and follows the [Repository Structure](../Repository%20Structure/README.md) conventions (including a `SECURITY.md`). * Each repository must contain a `README` describing its contents and providing instructions for building and running the component locally. +* All delivered code must comply with ECMWF [Copyright and Licensing](../Legal/Copyright-And-Licensing.md): an Apache-2.0 `LICENSE` at the repository root and per-file licence headers. New files should carry the machine-readable [SPDX/REUSE headers](../Legal/SPDX-and-REUSE.md) (see ADR-010), with the copyright holder set as agreed in the contract. ## 2. Deployment on ECMWF Infrastructure ECMWF must be able to deploy and operate every delivered component on its **own infrastructure**, independently of any environment maintained by the contractor. ECMWF will not assume responsibility for, or continue to use, contractor-hosted infrastructure. -* **Docker** is the required containerisation method. Every component that is containerised must be delivered with its **Dockerfile(s)** and documentation explaining how the containerisation works — what each image contains, how images are built, and how they are run. -* **Helm** and **Kubernetes** are the tools ECMWF uses to deploy applications. For simple applications, the Docker files alone are often sufficient for ECMWF to deploy the component on its own infrastructure. Where the contractor uses a more complex deployment process — for example, separately deployed backend and frontend components — the contractor must provide the **Helm and Kubernetes configuration** they use to deploy these, so that ECMWF can reproduce the deployment. +The deployment architecture — the containerisation and orchestration approach — **must be agreed with the Technical Officer**, since the appropriate approach differs between, for example, a multi-container web application and a data-production workflow. The tooling below is ECMWF's default; agree any deviation in advance. + +* **Docker** is ECMWF's standard containerisation method. Every component that is containerised must be delivered with its **Dockerfile(s)** and documentation explaining how the containerisation works — what each image contains, how images are built, and how they are run. +* **Helm** and **Kubernetes** are the tools ECMWF uses to deploy applications. For simple applications, the Docker files alone are often sufficient for ECMWF to deploy the component on its own infrastructure. Where the contractor uses a more complex deployment process — for example, separately deployed backend and frontend components — the contractor must provide the **Helm and Kubernetes configuration** they use to deploy these, so that ECMWF can reproduce the deployment. For applications with multiple containers, it is recommended that the deployment configuration is provided and documented in a **separate repository**. * Deployment recipes must be accompanied by **detailed, step-by-step instructions** sufficient for ECMWF to deploy the software from scratch on its own cluster, without reference to, or dependency on, the contractor's environment. * Instructions must cover deploying a change, deploying from scratch, and rolling back a deployment. * Any configuration that differs between environments (e.g. development, staging, production) must be documented, along with every environment variable, secret, and configuration value ECMWF must supply. @@ -55,6 +59,11 @@ ECMWF must be able to deploy and operate every delivered component on its **own ## 7. Access, Credentials, and Configuration +* **Secret values must never be committed** to the repository or its git history — document only the *names*, *locations*, and *regeneration procedures*. Repository history is scanned for leaked secrets (e.g. with `gitleaks`) before any publication, and a leaked credential must be rotated at source, not merely deleted in a later commit. * The README must summarise all secrets, keys, and configuration values required to run the application, and state where each should reside (e.g. Kubernetes secrets, environment variables). * For every secret, key, or credential that can or must be re-generated (e.g. API keys, signing keys, tokens, database passwords, TLS certificates), the README must document **how ECMWF regenerates it** — the service or tool used, the exact steps to follow, and where the new value must then be configured for the application to keep working. * Any credential bound to the contractor's personal or organisational accounts must be flagged as requiring replacement rather than transfer, with instructions for generating an equivalent value under ECMWF's own accounts. + +## Publication and open-sourcing + +Delivered repositories typically start **private** within the ECMWF organisation. If and when a repository is to be made public, ECMWF does so following [Open Sourcing Software at ECMWF](../Legal/Open-Sourcing-Software.md), which includes the open-source and security audit gates. Because any repository may later be audited for publication, contractors should keep history free of secrets and internal references from the outset (see Section 7). diff --git a/Guidelines/External-Contributions.md b/Guidelines/External-Contributions.md index 8eb30e7..ae8ca10 100644 --- a/Guidelines/External-Contributions.md +++ b/Guidelines/External-Contributions.md @@ -7,6 +7,8 @@ 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. +Contractors delivering a complete software service or product that ECMWF will own and operate must additionally follow the [Continuous Software Delivery](./Continuous-Software-Delivery.md) guidelines, which define *what* must be delivered (code, deployment recipes, data, supporting services, and credentials). + --- ## 1. Standard Contributions (Default Method) diff --git a/Guidelines/README.md b/Guidelines/README.md index 00da15c..fb8a300 100644 --- a/Guidelines/README.md +++ b/Guidelines/README.md @@ -10,5 +10,6 @@ Development guidelines for ECMWF software projects. - [Containerisation](./Containerisation.md) — guidelines for containerising ECMWF software - [Observability](./Observability.md) — observability guidelines for ECMWF services - [External Contributions](./External-Contributions.md) — guidelines for accepting external contributions to ECMWF projects +- [Continuous Software Delivery](./Continuous-Software-Delivery.md) — what contractors must deliver so ECMWF can own and operate a software service or product - [Security Vulnerability Disclosure](./Security-Vulnerability-Disclosure.md) — coordinated disclosure workflow using GitHub Private Vulnerability Reporting (PVR) and security advisories - [Testing](./Testing.md) — guidelines for unit, integration and regression testing, and for test suites for services diff --git a/README.md b/README.md index 3113246..10632c1 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ The Codex is a set of principles and guidelines for development of software and - [Observability](./Guidelines/Observability.md) - [ECMWF Software EnginE (ESEE)](./ESEE) - [External Contributions](./Guidelines/External-Contributions.md) +- [Continuous Software Delivery](./Guidelines/Continuous-Software-Delivery.md) - [Security Vulnerability Disclosure](./Guidelines/Security-Vulnerability-Disclosure.md) - [Documentation and Training](./Documentation%20and%20Training/) - [Contributing to External Projects](./Contributing%20Upstream/) From 59a78a47beb102c8c92716e57c859eb1abfcfcf9 Mon Sep 17 00:00:00 2001 From: Tiago Quintino Date: Wed, 8 Jul 2026 21:34:49 +0100 Subject: [PATCH 09/12] Address Copilot review on #64: number final section, Dockerfiles wording - Number the closing section '## 8. Publication and Open-Sourcing' to match the document's numbered structure (1-7). - Use 'Dockerfiles' consistently (was 'Docker files') in the deployment section. --- Guidelines/Continuous-Software-Delivery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Guidelines/Continuous-Software-Delivery.md b/Guidelines/Continuous-Software-Delivery.md index 7676c2f..421201b 100644 --- a/Guidelines/Continuous-Software-Delivery.md +++ b/Guidelines/Continuous-Software-Delivery.md @@ -31,7 +31,7 @@ ECMWF must be able to deploy and operate every delivered component on its **own The deployment architecture — the containerisation and orchestration approach — **must be agreed with the Technical Officer**, since the appropriate approach differs between, for example, a multi-container web application and a data-production workflow. The tooling below is ECMWF's default; agree any deviation in advance. * **Docker** is ECMWF's standard containerisation method. Every component that is containerised must be delivered with its **Dockerfile(s)** and documentation explaining how the containerisation works — what each image contains, how images are built, and how they are run. -* **Helm** and **Kubernetes** are the tools ECMWF uses to deploy applications. For simple applications, the Docker files alone are often sufficient for ECMWF to deploy the component on its own infrastructure. Where the contractor uses a more complex deployment process — for example, separately deployed backend and frontend components — the contractor must provide the **Helm and Kubernetes configuration** they use to deploy these, so that ECMWF can reproduce the deployment. For applications with multiple containers, it is recommended that the deployment configuration is provided and documented in a **separate repository**. +* **Helm** and **Kubernetes** are the tools ECMWF uses to deploy applications. For simple applications, the Dockerfiles alone are often sufficient for ECMWF to deploy the component on its own infrastructure. Where the contractor uses a more complex deployment process — for example, separately deployed backend and frontend components — the contractor must provide the **Helm and Kubernetes configuration** they use to deploy these, so that ECMWF can reproduce the deployment. For applications with multiple containers, it is recommended that the deployment configuration is provided and documented in a **separate repository**. * Deployment recipes must be accompanied by **detailed, step-by-step instructions** sufficient for ECMWF to deploy the software from scratch on its own cluster, without reference to, or dependency on, the contractor's environment. * Instructions must cover deploying a change, deploying from scratch, and rolling back a deployment. * Any configuration that differs between environments (e.g. development, staging, production) must be documented, along with every environment variable, secret, and configuration value ECMWF must supply. @@ -64,6 +64,6 @@ The deployment architecture — the containerisation and orchestration approach * For every secret, key, or credential that can or must be re-generated (e.g. API keys, signing keys, tokens, database passwords, TLS certificates), the README must document **how ECMWF regenerates it** — the service or tool used, the exact steps to follow, and where the new value must then be configured for the application to keep working. * Any credential bound to the contractor's personal or organisational accounts must be flagged as requiring replacement rather than transfer, with instructions for generating an equivalent value under ECMWF's own accounts. -## Publication and open-sourcing +## 8. Publication and Open-Sourcing Delivered repositories typically start **private** within the ECMWF organisation. If and when a repository is to be made public, ECMWF does so following [Open Sourcing Software at ECMWF](../Legal/Open-Sourcing-Software.md), which includes the open-source and security audit gates. Because any repository may later be audited for publication, contractors should keep history free of secrets and internal references from the outset (see Section 7). From 4d54fb9fd3345475454d850b7891150c4329b071 Mon Sep 17 00:00:00 2001 From: Tiago Quintino Date: Wed, 8 Jul 2026 21:37:33 +0100 Subject: [PATCH 10/12] Address Copilot review on #64: avoid implying delivery of secret values MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reword the External-Contributions pointer: contractors deliver credential *configuration and regeneration procedures*, never secret values themselves — consistent with Continuous Software Delivery Section 7. --- Guidelines/External-Contributions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Guidelines/External-Contributions.md b/Guidelines/External-Contributions.md index ae8ca10..1ed33ed 100644 --- a/Guidelines/External-Contributions.md +++ b/Guidelines/External-Contributions.md @@ -7,7 +7,7 @@ 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. -Contractors delivering a complete software service or product that ECMWF will own and operate must additionally follow the [Continuous Software Delivery](./Continuous-Software-Delivery.md) guidelines, which define *what* must be delivered (code, deployment recipes, data, supporting services, and credentials). +Contractors delivering a complete software service or product that ECMWF will own and operate must additionally follow the [Continuous Software Delivery](./Continuous-Software-Delivery.md) guidelines, which define *what* must be delivered (code, deployment recipes, data, supporting services, and credential configuration and regeneration procedures — never secret values themselves). --- From d883c6e1fa9e6930c01b3d170190d8de2d997456 Mon Sep 17 00:00:00 2001 From: Tiago Quintino Date: Wed, 8 Jul 2026 21:40:34 +0100 Subject: [PATCH 11/12] Address Copilot review on #64: use 'cookiecutter' to match Repository Structure Match the 'cookiecutter template' term used in Repository Structure/README.md (the doc this bullet links to). --- Guidelines/Continuous-Software-Delivery.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Guidelines/Continuous-Software-Delivery.md b/Guidelines/Continuous-Software-Delivery.md index 421201b..989ab0f 100644 --- a/Guidelines/Continuous-Software-Delivery.md +++ b/Guidelines/Continuous-Software-Delivery.md @@ -20,7 +20,7 @@ All source code must be delivered to ECMWF as one or more **GitHub repositories * Repositories are created by ECMWF staff via the Technical Officer, following the [Requesting a New Repository](../Legal/Requesting-New-Repository.md) procedure, and should be requested as early as possible so that development happens in the ECMWF organisation from the outset. * To enable ECMWF to create the repositories, the contractor must provide all of the information required as described in the [Software Management Plan](../Software%20Management%20Plan/README.md#5-new-repositories) guidelines. -* Each repository is initialised using the ECMWF cookie-cutter template and follows the [Repository Structure](../Repository%20Structure/README.md) conventions (including a `SECURITY.md`). +* Each repository is initialised using the ECMWF cookiecutter template and follows the [Repository Structure](../Repository%20Structure/README.md) conventions (including a `SECURITY.md`). * Each repository must contain a `README` describing its contents and providing instructions for building and running the component locally. * All delivered code must comply with ECMWF [Copyright and Licensing](../Legal/Copyright-And-Licensing.md): an Apache-2.0 `LICENSE` at the repository root and per-file licence headers. New files should carry the machine-readable [SPDX/REUSE headers](../Legal/SPDX-and-REUSE.md) (see ADR-010), with the copyright holder set as agreed in the contract. From 69ceff72382f122bd881e82722c58966b157db6c Mon Sep 17 00:00:00 2001 From: Tiago Quintino Date: Wed, 8 Jul 2026 21:43:48 +0100 Subject: [PATCH 12/12] Address Copilot review on #64: link ADR-010, retitle section 3 - Make the ADR-010 reference a clickable link (matches other ADR references). - Retitle section 3 'Source Code' -> 'Repository Documentation' to match its content (cross-repo README/branch documentation). --- Guidelines/Continuous-Software-Delivery.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Guidelines/Continuous-Software-Delivery.md b/Guidelines/Continuous-Software-Delivery.md index 989ab0f..c903497 100644 --- a/Guidelines/Continuous-Software-Delivery.md +++ b/Guidelines/Continuous-Software-Delivery.md @@ -22,7 +22,7 @@ All source code must be delivered to ECMWF as one or more **GitHub repositories * To enable ECMWF to create the repositories, the contractor must provide all of the information required as described in the [Software Management Plan](../Software%20Management%20Plan/README.md#5-new-repositories) guidelines. * Each repository is initialised using the ECMWF cookiecutter template and follows the [Repository Structure](../Repository%20Structure/README.md) conventions (including a `SECURITY.md`). * Each repository must contain a `README` describing its contents and providing instructions for building and running the component locally. -* All delivered code must comply with ECMWF [Copyright and Licensing](../Legal/Copyright-And-Licensing.md): an Apache-2.0 `LICENSE` at the repository root and per-file licence headers. New files should carry the machine-readable [SPDX/REUSE headers](../Legal/SPDX-and-REUSE.md) (see ADR-010), with the copyright holder set as agreed in the contract. +* All delivered code must comply with ECMWF [Copyright and Licensing](../Legal/Copyright-And-Licensing.md): an Apache-2.0 `LICENSE` at the repository root and per-file licence headers. New files should carry the machine-readable [SPDX/REUSE headers](../Legal/SPDX-and-REUSE.md) (see [ADR-010](../ADR/ADR-010-SPDX-License-Identifiers-and-REUSE-Headers.md)), with the copyright holder set as agreed in the contract. ## 2. Deployment on ECMWF Infrastructure @@ -37,7 +37,7 @@ The deployment architecture — the containerisation and orchestration approach * Any configuration that differs between environments (e.g. development, staging, production) must be documented, along with every environment variable, secret, and configuration value ECMWF must supply. * Any value, endpoint, or credential currently hardcoded or otherwise bound to the contractor's infrastructure must be clearly identified, with guidance on what ECMWF must change. -## 3. Source Code +## 3. Repository Documentation * Each repository's README must list every repository delivered for the project (e.g. frontend, backend, infrastructure, data pipelines), matching the repository names provided under Section 1, with a one-line description of each, and link to the others. * For each repository, the README must state the main branch, any branching conventions in use, and the location of build-and-run instructions.