diff --git a/source/Development/Diagnostics/lfric_diagnostics.rst b/source/Development/Diagnostics/lfric_diagnostics.rst index 409a8fb0..b6f27657 100644 --- a/source/Development/Diagnostics/lfric_diagnostics.rst +++ b/source/Development/Diagnostics/lfric_diagnostics.rst @@ -69,7 +69,7 @@ Field requests can be grouped to be output to different file streams. included in the ``iodef.xml`` file for a given application configuration. XIOS is a highly complex and flexible parallel IO system with post-processing -capabilites, including the ability to apply time and spatial processing as +capabilities, including the ability to apply time and spatial processing as well as combine multiple fields. It is developed at IPSL. .. caution:: diff --git a/source/Development/TestSuites/multi-repo_testing.rst b/source/Development/TestSuites/multi-repo_testing.rst index 5d9c8f13..913e5768 100644 --- a/source/Development/TestSuites/multi-repo_testing.rst +++ b/source/Development/TestSuites/multi-repo_testing.rst @@ -35,7 +35,7 @@ local git clone, in which case it should take the form, ``source: :/path/to/clone``. The ``ref`` setting takes a git tree-ish value. Common settings will be a commit -hash, a tag or a branch name as demostrated by the examples below. At +hash, a tag or a branch name as demonstrated by the examples below. At release, the refs will be tags and will be changed to the long form of the relevant commit hash as part of linked pull requests. @@ -43,7 +43,7 @@ If left blank the behaviour depends on the source: * **a GitHub source:** the Head of the repositories default branch will be used. * **a local clone:** the state of the repository at source extraction time will be used. - It is recommened to set a ref when setting the source to a local clone. That way + It is recommended to set a ref when setting the source to a local clone. That way if you switch branches in the clone, the correct branch for testing will be used. Various different configurations of an lfric_core source are shown below with an @@ -66,7 +66,7 @@ explanation of each, source: git@github.com:MetOffice/lfric_core.git ref: - # A Users fork of the lfric_core repoistory, on branch my_branch + # A Users fork of the lfric_core repository, on branch my_branch lfric_core: source: git@github.com:UserName/lfric_core.git ref: my_branch diff --git a/source/Development/TestSuites/um.rst b/source/Development/TestSuites/um.rst index 1db2fa20..fd09a03a 100644 --- a/source/Development/TestSuites/um.rst +++ b/source/Development/TestSuites/um.rst @@ -60,7 +60,7 @@ groups, and that you can specify more than one at once, e.g. | | team. | +--------------------+----------------------------------------------------------+ | all | The complete test suite, including all longer runs and | -| | less commonly used utilites. This is run automatically | +| | less commonly used utilities. This is run automatically | | | every week and monitored by the SSD team. All | | | :ref:`KGO ` changing PRs need to run this group. | +--------------------+----------------------------------------------------------+ diff --git a/source/Development/kgo.rst b/source/Development/kgo.rst index 5de475f5..e31f155a 100644 --- a/source/Development/kgo.rst +++ b/source/Development/kgo.rst @@ -61,10 +61,10 @@ such changes onto ``main``. When preparing your change for review: 4. If you are adding new checksums, ``git add`` the files. - 5. You can check the new kgo updated properly by retiggering tasks in + 5. You can check the new kgo updated properly by retriggering tasks in the test suite. First retrigger ``export-source``, and then when complete ``export-source_ex1a`` if new checksums are present there - (there is no need to retigger spice). You may need to change the + (there is no need to retrigger spice). You may need to change the maximum window extent of the gui in order to see the succeeded tasks. Now you can retrigger the failed checksums - these should now pass if the kgo was updated in the clone correctly. @@ -98,7 +98,7 @@ such changes onto ``main``. When preparing your change for review: .. tip:: - More details on the KGO update proceedures for all repositories can be + More details on the KGO update procedures for all repositories can be found on the :ref:`How to Commit page`. .. toctree:: diff --git a/source/FurtherDetails/ai.rst b/source/FurtherDetails/ai.rst index 57fe32cd..6b1c3bf8 100644 --- a/source/FurtherDetails/ai.rst +++ b/source/FurtherDetails/ai.rst @@ -9,25 +9,165 @@ AI Policy ========= -Please ensure that when using Generative AI tools, appropriate guardrails are -in place and contributions have correct attribution. For Met Office -contributors, this includes adhering to the Use of Generative AI policy. -Contributors from other institutions should check if their institution has -similar policies, and follow the local policy. - -Code where Generative AI tools have been used needs to have clear attribution to -meet the Met Office Generative AI policy. This includes attribution in the -commit message and in each modified file. Any file where a modification has been -made with Generative AI assistance must have a comment immediately before the -module level docstring, containing: - -.. code-block:: - - # Some of the content of this file has been produced with the assistance of - ." - -where ```` should be replaced with the specific name of -the tool such as `` Github Copilot Enterprise`` (e.g. Met -Office Github Copilot Enterprise), ``Github Copilot Personal``, -``ChatGPT GPT-4``, etc. For Met Office contributors, Met Office Github Copilot -Enterprise is the only approved Generative AI tool. +The primary objective of this policy is to prevent introduction of +Intellectual Property Rights (IPR) restricted code into the simulation systems. + +This policy is written so it can be reused across open source repositories +using the BSD-3-Clause licence, which does not define requirements for +AI-assisted contributions. + +Scope +----- + +This policy applies to AI-assisted contributions in: + +* source code +* tests +* scripts and configuration +* documentation files containing code examples + +For this policy, AI-assisted means content generated, completed, or +substantially refactored by a Generative AI tool. + +Core Principles and Tool Restrictions +------------------------------------- + +* **Risk of Public-Domain AI**: AI tools trained on public repositories can emit + code that violates open-source licences or copyrights. +* **No Free/Personal-Tier Tools**: Use of free or personal-tier AI coding tools + is *strictly prohibited* for project contributions. +* **Approved Enterprise-Tier Tools Only**: Contributors may only use + enterprise-tier AI tools approved by their employing organisation or the + repository maintainers. +* **Contributor Responsibility**: The human contributor is responsible for all + submitted content, including correctness, licensing checks, and project + standards compliance. + +Approved enterprise-tier tools +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +An approved tool must satisfy all of the following: + +* enterprise-tier licence with auditable terms of use +* terms that allow open source contribution workflows +* explicit organisational approval by employer or project maintainers +* controls appropriate to institutional IPR and data handling requirements + +If a contributor cannot use an approved enterprise-tier tool, code must be +written manually. + +Legal framing and BSD-3-Clause compatibility +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This policy adds process controls for AI use. It does not alter the +BSD-3-Clause licence terms, warranties, or disclaimers. + +Attribution and review requirements in this policy are mandatory contribution +conditions for the simulation systems repositories. + +Attribution Requirements +------------------------ + +If an approved Generative AI tool is used, you must provide attribution in two +places: + +**1. the source file header** + +Add a comment near the top of the file. Use the native comment style for the +language, for example: + +.. tab-set:: + + .. tab-item:: Fortran + + .. code-block:: f90 + + ! Some content in this file was generated or refactored with assistance + ! from [Tool Name] ([Model/Version]) on [YYYY-MM-DD]. + + .. tab-item:: Python + + .. code-block:: python + + # Some content in this file was generated or refactored with assistance + # from [Tool Name] ([Model/Version]) on [YYYY-MM-DD]. + + .. tab-item:: C++ + + .. code-block:: cpp + + // Some content in this file was generated or refactored with assistance + // from [Tool Name] ([Model/Version]) on [YYYY-MM-DD]. + +**2. the commit message** + +Your git commit message must identify the tool and what it assisted with, for +example: + +.. code-block:: text + + Refactor spatial interpolation routines to improve performance. + + - Co-authored-by: [Tool Name] ([Model/Version]) + - Assisted-by: [Tool Name] ([Model/Version]) + for spatial interpolation optimisation. + +Attribution must be specific enough for later audit. Include tool name, +model/version where available, and date in the source file header. + +Internal example (non-normative) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For Met Office contributors, the following is an acceptable example tool +identifier: + +* Met Office GitHub Copilot Enterprise (Claude Sonnet 4.6) + +This example is provided for convenience. It does not change the requirement +that only approved enterprise-tier tools may be used. + +Code Review Guidelines +---------------------- + +Reviewers must remember that AI-generated code is not self-authenticating. +The human contributor remains fully responsible for its contents. + +Reviewer Checklist Matrix +^^^^^^^^^^^^^^^^^^^^^^^^^ + ++------+--------------------+------------------------------+------------------------+ +| Step | Action | Pass Criteria | Fail Action | ++======+====================+==============================+========================+ +| 1 | Check file header | Explicitly names approved | Block merge if | +| | and commit message | enterprise-tier tool and | free/personal tier | +| | | includes required attribution| is used | ++------+--------------------+------------------------------+------------------------+ +| 2 | Check licence | No obvious proprietary or | Pause merge and | +| | compatibility | or restrictively licensed | request proof of | +| | | copy-pasted snippets | origin/provenance | ++------+--------------------+------------------------------+------------------------+ +| 3 | Assess Logic and | Reviewer understands every | Request revisions for | +| | Edge Cases | line; edge cases are handled | "black box" code | ++------+--------------------+------------------------------+------------------------+ +| 4 | Run Test Suite | Code passes all unit, | Block merge until | +| | | integration, and | tests pass natively | +| | | regression tests | | ++------+--------------------+------------------------------+------------------------+ + +Enforcement and Remediation +--------------------------- + +The enforcement model is corrective-first, except where banned tools or +unresolved IPR risk is involved. + +* Missing attribution: request correction before merge. +* Free/personal-tier AI use: block merge until replaced with compliant + contribution. +* Suspected licence/IPR conflict: pause review, request provenance, and escalate + to maintainers. + +If an IPR issue is discovered after merge, maintainers should choose one of: + +* revert the change +* rewrite affected code +* retain with verified, compatible attribution where legally valid diff --git a/source/FurtherDetails/dos_donts.rst b/source/FurtherDetails/dos_donts.rst index e8457de1..f8559794 100644 --- a/source/FurtherDetails/dos_donts.rst +++ b/source/FurtherDetails/dos_donts.rst @@ -49,7 +49,7 @@ and resolving any conflicts. **Licensing** - Don't add code to any project (or to any branch thereof) that has been developed under a different license without agreement from the Simulation Systems and Deployment Team. This includes lifting Fortran code or -text from books. Our repositiories must not infringe copyright. +text from books. Our repositories must not infringe copyright. **Request support by raising an issue**. Newly raised issues are not monitored. Use the appropriate :ref:`support` channels. diff --git a/source/FurtherDetails/glossary.rst b/source/FurtherDetails/glossary.rst index 31313051..e6929faa 100644 --- a/source/FurtherDetails/glossary.rst +++ b/source/FurtherDetails/glossary.rst @@ -49,7 +49,7 @@ Linked Pull Request (Linked PR): Overarching Issue: Where a piece of work has been split into multiple sections an overarching issue can be used to track this work. It should be closed when the whole arc - has been completed. GitHub also allows subissues which can be created from + has been completed. GitHub also allows sub-issues which can be created from the overarching issue. Regression: diff --git a/source/FurtherDetails/who.rst b/source/FurtherDetails/who.rst index 98eed3fb..d116a6ef 100644 --- a/source/FurtherDetails/who.rst +++ b/source/FurtherDetails/who.rst @@ -143,7 +143,7 @@ Core Capability Development Team: Tools and Collaborative Development Team: The TCD Team is responsible for the development and integration of third - party tools with LFRic including Psyclone, XIOS and LFRic Inputs. + party tools with LFRic including PSyclone, XIOS and LFRic Inputs. The team can be contacted at ToolsCollabDevTeam@metoffice.gov.uk @@ -154,7 +154,7 @@ Tools and Collaborative Development Team: HPC Optimisation Team --------------------- -The HPC optimistation team take a general lead in matters relating to compute +The HPC optimisation team take a general lead in matters relating to compute performance of the UM, LFRic and other systems. * Examine and improve the performance and scalability of the UM and coupled diff --git a/source/Reviewers/nightlytesting.rst b/source/Reviewers/nightlytesting.rst index 68cd83e9..758ca8f6 100644 --- a/source/Reviewers/nightlytesting.rst +++ b/source/Reviewers/nightlytesting.rst @@ -17,7 +17,7 @@ Nightly Testing Modifying and Installing Testing -------------------------------- -Nightly testing is controlled by 2 cronfiles, ``auto-gen_testing.cron`` and +Nightly testing is controlled by 2 cron files, ``auto-gen_testing.cron`` and ``manual.cron`` both located in ``~/Crontabs/``. The first is automatically generated the script ``generate_test_suite_cron.py`` which is stored in the SimSys_Scripts GitHub repo and controls the launching and clean up of the @@ -151,6 +151,6 @@ items can be added/edited. When done click ``submit`` and then ``Trigger`` .. important:: When finished Keyboard terminate the cylc url command and choose y when - prompted. This shutsdown the cylc server and prevents multiple connections + prompted. This shuts down the cylc server and prevents multiple connections opening. diff --git a/source/Reviewers/releases/release_notes.rst b/source/Reviewers/releases/release_notes.rst index 4b08dcf9..7085a56b 100644 --- a/source/Reviewers/releases/release_notes.rst +++ b/source/Reviewers/releases/release_notes.rst @@ -85,7 +85,7 @@ Create a new wiki page: * [LFRic Apps vnX.Y](https://github.com/MetOffice/lfric_apps/releases/tag/vnX.Y) * [LFRic Core vnX.Y](https://github.com/MetOffice/lfric_core/releases/tag/vnX.Y) * [UM vnX.Y](https://github.com/MetOffice/um/releases/tag/vnX.Y) (private within the MetOffice organisation) - * [JULES vnX.Y](https://github.com/MetOffice/jules/releases/tag/vnX.Y) (currently private, will hopefully soon be publically available) + * [JULES vnX.Y](https://github.com/MetOffice/jules/releases/tag/vnX.Y) ## Key Highlights * A few highlights the affect multiple repositories diff --git a/source/Reviewers/releases/shared_accounts.rst b/source/Reviewers/releases/shared_accounts.rst index 13627d4a..60f8ed59 100644 --- a/source/Reviewers/releases/shared_accounts.rst +++ b/source/Reviewers/releases/shared_accounts.rst @@ -9,7 +9,7 @@ Repo and Shared Accounts Permissions ==================================== -Modify SSD Team Github Permissions: +Modify SSD Team GitHub Permissions: * https://github.com/orgs/MetOffice/teams/ssdteam diff --git a/source/Reviewers/releases/shumlib_release.rst b/source/Reviewers/releases/shumlib_release.rst index f0a76e62..1b344399 100644 --- a/source/Reviewers/releases/shumlib_release.rst +++ b/source/Reviewers/releases/shumlib_release.rst @@ -62,7 +62,7 @@ First install on azspice, .. code-block:: shell - export SPACKDIR= # Set this as the Spackadmin Data Directory (no trailing slash) + export SPACKDIR= # Set this as the spackadmin Data Directory (no trailing slash) BUILD_DESTINATION=$UMDIR/shumlib/shumlib-YYYY.MM.V scripts/meto_install_shumlib.sh azspice Then ssh to each of EXAB, EXCD and EXZ and install there, diff --git a/source/Reviewers/releases/um_main_release.rst b/source/Reviewers/releases/um_main_release.rst index e2e61df6..7a742a10 100644 --- a/source/Reviewers/releases/um_main_release.rst +++ b/source/Reviewers/releases/um_main_release.rst @@ -316,7 +316,7 @@ appear in the correct place. Do this by running, and check that ``~umadmin/cylc_run/umx.y_install/runN/share/vnX.Y`` exists and is the new version number. If that has worked, change the -CENTRALL_INSTALL flag to true and rerun, +``CENTRAL_INSTALL`` flag to ``true`` and rerun, .. code-block:: shell diff --git a/source/WorkingPractices/forking.rst b/source/WorkingPractices/forking.rst index b569dad3..d77f0ed3 100644 --- a/source/WorkingPractices/forking.rst +++ b/source/WorkingPractices/forking.rst @@ -68,7 +68,7 @@ the owner. Add ``--clone`` to immediately clone the forked repo -Disable Github Actions in your fork +Disable GitHub Actions in your fork ----------------------------------- It is a good idea to disable GitHub actions on your fork otherwise you will diff --git a/source/WorkingPractices/gh_authorisation.rst b/source/WorkingPractices/gh_authorisation.rst index 3d4ed989..79f9f602 100644 --- a/source/WorkingPractices/gh_authorisation.rst +++ b/source/WorkingPractices/gh_authorisation.rst @@ -6,7 +6,7 @@ .. _gh_authorisation: -Setting Up Github Authorisations +Setting Up GitHub Authorisations ================================ Initial Setup @@ -56,7 +56,7 @@ This is worth doing on all platforms you have access to where git is available .. tip:: - Github has functionality that can keep your email address private. + GitHub has functionality that can keep your email address private. * Navigate to ``_ * Enable the **Keep my email addresses private** setting. This should @@ -142,7 +142,7 @@ or individually by replacing all calls to `git config --global` with `git config` in each local git repository that you want to configure. -First configure your Github SSH keys to include a signing key, +First configure your GitHub SSH keys to include a signing key, if this isn't already set up. At https://github.com/settings/keys : @@ -166,7 +166,7 @@ Then configure git locally at the command line: # Substitute `git config` for `git config --global` for by-repository configuration git config --global gpg.format ssh # Noting that the is to the public (`.pub`) part, and must match - # the Github registered public key and the allowed-signers key. + # the GitHub registered public key and the allowed-signers key. git config --global user.signingkey .pub git config --global gpg.ssh.allowedSignersFile ~/.config/git/allowed-signers git config --global commit.gpgsign true @@ -181,8 +181,8 @@ To check this is working locally, add a commit, then check the commit log: which should show details of the signed commit. -To check that this is working on Github, then push a commit to -a branch on Github (on a personal fork), then browse to the commit list. +To check that this is working on GitHub, then push a commit to +a branch on GitHub (on a personal fork), then browse to the commit list. There should be a green `Verified` label beside each signed commit. @@ -215,7 +215,7 @@ for details of authenticating. .. _github_pat: -Github Personal Access Tokens +GitHub Personal Access Tokens ----------------------------- Using GitHub tokens is optional for most test suites, as SSH authentication is diff --git a/source/WorkingPractices/gh_dev_init.rst b/source/WorkingPractices/gh_dev_init.rst index 240abd87..479bb8d7 100644 --- a/source/WorkingPractices/gh_dev_init.rst +++ b/source/WorkingPractices/gh_dev_init.rst @@ -6,7 +6,7 @@ .. _gh_dev_init: -Beginning a Github Development +Beginning a GitHub Development ============================== This section will guide you through the development process assuming you are diff --git a/source/WorkingPractices/pull_requests.rst b/source/WorkingPractices/pull_requests.rst index 5ad9b4ac..9d445b2a 100644 --- a/source/WorkingPractices/pull_requests.rst +++ b/source/WorkingPractices/pull_requests.rst @@ -168,7 +168,7 @@ Updating a branch Most development work in simulation-systems repositories will take place on a branch created from ``stable``. Therefore it will need to be updated to match -the latest changes from ``main`` when a pull request is open. Github provides +the latest changes from ``main`` when a pull request is open. GitHub provides functionality to do this in the browser, with the ability to fix merge conflicts. Alternatively, you can do this from a terminal using git. For more details see :ref:`updating a branch `. diff --git a/source/WorkingPractices/reviews.rst b/source/WorkingPractices/reviews.rst index 3cebdd06..018d88ab 100644 --- a/source/WorkingPractices/reviews.rst +++ b/source/WorkingPractices/reviews.rst @@ -5,7 +5,7 @@ Review Process .. tip:: - Github allows reviewers to directly make suggestions to the code. This is + GitHub allows reviewers to directly make suggestions to the code. This is very useful for easily suggesting changes. However, the developer should always check carefully that the change is sensible and doesn't contain any errors or bugs. diff --git a/source/WorkingPractices/working_practices.rst b/source/WorkingPractices/working_practices.rst index f1092a4f..71cd24b3 100644 --- a/source/WorkingPractices/working_practices.rst +++ b/source/WorkingPractices/working_practices.rst @@ -52,7 +52,7 @@ The release cycle is overseen by the Simulation Systems and Deployment Team with the oversight and support of the LFRic Apps Governance Group, who impartially consider the needs of all developers and users. -Git/Github Definitions +Git/GitHub Definitions ---------------------- Some commonly used git/GitHub definitions. Further definitions can be found in @@ -64,7 +64,7 @@ Clone Continuous Integration Testing that is run on GitHub based on the changes in a pull request. For - simulation-sytems repositories, this is run in addition to local rose-stem + simulation-systems repositories, this is run in addition to local rose-stem testing. It is commonly referred to as CI. Fork @@ -88,7 +88,7 @@ Pull Request Remote The version of either the upstream or the forked repository that is hosted - by Github. + by GitHub. Upstream The primary or parent repository, owned by the MetOffice GitHub @@ -111,10 +111,10 @@ branches to be added). branch, but will regularly be ahead. * ``stable`` - This branch represents the codebase at a version release and will generally remain unchanged throughout a release cycle. New branches - should be made from this branch (or from a release tag.) Only new releases + should be made from this branch (or from a release tag). Only new releases and small hotfixes to a release will be merged back into this branch. -All general development for Simulation Systems Github repositories will take +All general development for Simulation Systems GitHub repositories will take place on forks of that repository. It is the responsibility of the developer to maintain their own fork. See :ref:`forking` for advice on forking. @@ -185,7 +185,7 @@ Before You Start .. note:: In the following Working Practices, we will endeavour to provide options - for using the Github Web Interface and the ``gh`` cli where possible. + for using the GitHub Web Interface and the ``gh`` cli where possible. Further information will be available in the GitHub documentation. To get started with the ``gh`` cli, see the `gh quickstart guide diff --git a/source/accessibility.rst b/source/accessibility.rst index 27020217..36ba827e 100644 --- a/source/accessibility.rst +++ b/source/accessibility.rst @@ -10,7 +10,7 @@ .. _accessibility: Accessibility statement for the Simulation Systems website -########################################################## +========================================================== Details on producing an accessibility statement can be found on the `Central Digital & Data Office government website`_. @@ -55,7 +55,7 @@ Reporting accessibility problems with this website We're always looking to improve the accessibility of this website. If you find any problems not listed on this page or think we're not meeting accessibility -requirements, emailML-Simulation_Systems_and_Deployment@metoffice.gov.uk. +requirements, email ML-Simulation_Systems_and_Deployment@metoffice.gov.uk. Enforcement procedure --------------------- @@ -135,16 +135,13 @@ This statement was prepared on 24 September 2025. It was last reviewed on 24 Sep https://www.gov.uk/government/publications/sample-accessibility-statement/sample-accessibility-statement-for-a-fictional-public-sector-website .. _Met Office: https://www.metoffice.gov.uk/ .. _AbilityNet: https://abilitynet.org.uk/ - -.. _Public Sector Bodies (Websites and Mobile Applications) (No. 2) - Accessibility Regulations 2018 legislation: +.. _Public Sector Bodies (Websites and Mobile Applications) (No. 2) Accessibility Regulations 2018 legislation: https://www.legislation.gov.uk/uksi/2018/952/regulation/4 .. _Equality Advisory and Support Service: https://www.equalityadvisoryservice.com/ - -.. _Github issue: https://github.com/MetOffice/simulation-systems/issues/new -.. _metoffice.github.io/simulation-systems: https://metoffice.github.io/simulation-systems +.. _metoffice.github.io/simulation-systems: + https://metoffice.github.io/simulation-systems .. _Web Content Accessibility Guidelines version 2.2: https://www.w3.org/TR/WCAG22/