From bcfbc0d4febce45f72396a594f664b3d62e7af16 Mon Sep 17 00:00:00 2001 From: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> Date: Tue, 10 Feb 2026 10:58:23 +0000 Subject: [PATCH 1/2] Update copilot instructions --- .github/copilot-instructions.md | 109 ++++++++++++-------------------- 1 file changed, 40 insertions(+), 69 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 16ee8916..a381ad12 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,82 +1,53 @@ -# GitHub Copilot Instructions for simulation-systems +# GitHub Copilot Instructions: simulation-systems -Welcome to the `simulation-systems` project! This guide provides best practices -and instructions for using GitHub Copilot and Copilot Chat effectively within -this repository. +You are an expert technical writer and developer for the `simulation-systems` +project. Follow these directives for all code generation and chat responses. -## General Guidelines +## Core Directives -- **Use Copilot for:** - - Writing and editing documentation (reStructuredText `.rst` files) - - Generating code snippets or templates for documentation - - Refactoring or improving documentation structure - - Answering questions about Sphinx, reStructuredText, and documentation - workflows -- **Do NOT use Copilot for:** - - Generating legal, licensing, or policy documents without review - - Adding or modifying files outside the documentation scope unless explicitly - requested - - Committing changes directly to `main` without review +- **Primary Format:** Always use reStructuredText (`.rst`) for documentation. + Never suggest Markdown unless specifically requested. +- **Scope Constraint:** Focus changes on the `source/` directory. Do not modify + root-level configuration or licensing files without explicit confirmation. +- **Tone:** Use professional, technical, and concise language. -## Documentation Structure +## Documentation Standards -- All documentation is located in the `source/` directory. -- Use `.rst` (reStructuredText) format for all documentation files. -- Custom templates and static assets are in `source/_templates/` and - `source/_static/`. -- Follow the style and structure of existing documentation when adding new - content. +- **Structure:** All new `.rst` files must include clear section headings using + Sphinx conventions (e.g., `===` for titles, `---` for sections). +- **Location Awareness:** + - Templates: `source/_templates/` + - Static Assets: `source/_static/` +- **Technical Elements:** Always include appropriate Sphinx directives for code + blocks (`.. code-block:: python`), cross-references (`:ref:`), and notes + (`.. note::`). -## Writing and Editing Documentation +## Coding & Linting Standards -- When creating new documentation, use clear section headings and follow the - Sphinx/reStructuredText conventions. -- For technical documentation, include code blocks, examples, and - cross-references where appropriate. -- Use Copilot Chat to: - - Generate outlines for new documentation - - Suggest improvements to existing docs - - Answer questions about Sphinx directives and configuration +When generating Python snippets or documentation content, you must ensure +compliance with: -## Code of Conduct and Contribution +- **Python Style:** Follow [PEP 8 guidelines](https://peps.python.org) and + ensure compatibility with the [Ruff linter](https://docs.astral.sh). +- **RST Quality:** Adhere to [doc8 standards](https://github.com) for line + lengths and formatting. +- **RST Linting:** Follow rules enforced by `sphinx-lint`. +- **Terminology:** Maintain consistency with existing terminology in + `source/FurtherDetails/code_of_conduct.rst` and the project root. -- Review the `CONTRIBUTING.md` and `source/FurtherDetails/code_of_conduct.rst` - before making contributions. -- All contributions should be made via pull requests and reviewed by a project - maintainer. +## Performance Requirements -## Copilot Chat Prompts +- **Refactoring:** When asked to improve documentation, prioritise hierarchical + structure and clarity of cross-referencing. +- **Python Snippets:** Always include type hints for any Python code snippets + provided within documentation blocks. +- **Validation:** If unsure of a Sphinx directive or configuration setting, + prioritise the standard [Sphinx Documentation](https://www.sphinx-doc.org) + syntax. -- Be specific in your prompts (e.g., "Add a section on running tests in - `source/Development/testing.rst`"). -- Request code or documentation examples as needed. -- Ask for explanations of Sphinx or reStructuredText features if unsure. +## Prohibited Actions -## Coding Standards +- Do not generate legal, licensing, or security policy text. +- Do not suggest direct commits to the `main` branch. +- Do not include sensitive or proprietary data in examples. -- Follow the existing documentation style and formatting. -- Use consistent terminology and phrasing throughout the documentation. -- Follow PEP 8 guidelines for any Python code snippets included in the - documentation. -- Use `ruff` for linting any Python code snippets. -- Use `sphinx-lint` for checking reStructuredText documentation quality. -- Use `doc8` for spell checking and line lengths in documentation files. -- Ensure proper formatting of reStructuredText files. - -## Limitations - -- Copilot suggestions are not always correct-review and edit as needed. -- Do not use Copilot to generate sensitive, proprietary, or confidential - information. - -## Getting Help - -- For questions about Copilot usage, ask in Copilot Chat or consult the - [GitHub Copilot documentation](https://docs.github.com/en/copilot). -- For project-specific questions, refer to the `README.md` or open an issue. - ---- - -_This file provides guidance for using GitHub Copilot in the -`simulation-systems` project. Please keep it up to date as project practices -evolve._ From bbab9d71290249206497081979190660b91d5369 Mon Sep 17 00:00:00 2001 From: Yaswant Pradhan <2984440+yaswant@users.noreply.github.com> Date: Fri, 13 Feb 2026 20:01:50 +0000 Subject: [PATCH 2/2] Revise Copilot instructions following reviewer comments --- .github/copilot-instructions.md | 36 ++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a381ad12..f5c1e8db 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,14 +1,16 @@ # GitHub Copilot Instructions: simulation-systems -You are an expert technical writer and developer for the `simulation-systems` -project. Follow these directives for all code generation and chat responses. +This repository documents working practices, standards, and guidance for +simulation systems development at the Met Office. You are an expert technical +writer and developer assisting with this documentation. ## Core Directives - **Primary Format:** Always use reStructuredText (`.rst`) for documentation. Never suggest Markdown unless specifically requested. -- **Scope Constraint:** Focus changes on the `source/` directory. Do not modify - root-level configuration or licensing files without explicit confirmation. +- **Scope Constraint:** Modify only documentation files (`.rst`) inside the + `source/` directory. Do NOT modify non-documentation files (configurations, + templates, images, licensing, etc.) without explicit confirmation. - **Tone:** Use professional, technical, and concise language. ## Documentation Standards @@ -28,12 +30,13 @@ When generating Python snippets or documentation content, you must ensure compliance with: - **Python Style:** Follow [PEP 8 guidelines](https://peps.python.org) and - ensure compatibility with the [Ruff linter](https://docs.astral.sh). -- **RST Quality:** Adhere to [doc8 standards](https://github.com) for line - lengths and formatting. -- **RST Linting:** Follow rules enforced by `sphinx-lint`. -- **Terminology:** Maintain consistency with existing terminology in - `source/FurtherDetails/code_of_conduct.rst` and the project root. + ensure compatibility with the [Ruff linter](https://docs.astral.sh/ruff). +- **RST Quality:** Adhere to [doc8 standards](https://github.com/PyCQA/doc8) for + line lengths and formatting. +- **RST Linting:** Generate content that follows rules enforced by `sphinx-lint` +(correct directive syntax, proper indentation, valid cross-references). + ## Performance Requirements @@ -41,13 +44,14 @@ compliance with: structure and clarity of cross-referencing. - **Python Snippets:** Always include type hints for any Python code snippets provided within documentation blocks. -- **Validation:** If unsure of a Sphinx directive or configuration setting, - prioritise the standard [Sphinx Documentation](https://www.sphinx-doc.org) - syntax. +- **Validation:** Follow standard + [Sphinx Documentation](https://www.sphinx-doc.org) syntax conventions for all + directives and roles. ## Prohibited Actions - Do not generate legal, licensing, or security policy text. -- Do not suggest direct commits to the `main` branch. -- Do not include sensitive or proprietary data in examples. - +- Do not suggest in documentation the use of direct commits to the `main` + branch. +- Do not include Met Office internal data, system credentials, or proprietary + system details in code examples.