Explainability improvements (#54)

* Cleaner text for notify-updates.

* Add a templating README.

* Update main README.

* Note on placeholders.

* Be more specific about template updates AND creation.

Co-authored-by: Patrick Peglar <patrick.peglar@metoffice.gov.uk>

* Remember to include README in the template index.

---------

Co-authored-by: Patrick Peglar <patrick.peglar@metoffice.gov.uk>

Author: trexfeathers

README.md

@@ -10,8 +10,7 @@ Organisational level things such as the SciTools README and organisation workflo
 [SciTools Peloton project](https://github.com/orgs/SciTools/projects/13?pane=info).
   See also [`.github/workflows/peloton.yml`](.github/workflows/peloton.yml).
 - [`./templates`](./templates) - tooling for standardising files across
-SciTools repos. See also 
-[`.github/workflows/template-sync.yml`](.github/workflows/template-sync.yml).
+SciTools repos.
 
 ## Possible future uses
 

templates/README.md

@@ -0,0 +1,51 @@
+# Templating
+
+SciTools developers manage several similar repositories. Where the same files
+are used across multiple repositories, it helps to keep them as similar as
+possible. We achieve this by storing templates for common files in this
+directory.
+
+## Benefits
+
+- Smoother transition for developers when switching between repositories.
+- Encodes agreed SciTools best practices.
+- Avoids useful ideas being isolated to the repository where they were first 
+tried. 
+- A way to share simple scripting across repositories without needing an
+installable package or similar - less overhead and easier to follow.
+
+## How it works
+
+[`_templating_config.json`](_templating_config.json) is the 'index' of all the
+templates and how they map to files in the SciTools repositories.
+
+[`_templating_scripting.py`](_templating_scripting.py) contains the logic for
+communicating template updates around SciTools - using GitHub issues and
+comments. It is called by two GitHub Actions workflows:
+
+- [`template-update-notification.yml`](../.github/workflows/template-update-notification.yml)
+uses the `notify_updates()` function to raise issues on all relevant
+repositories when a template is updated, or a new one created.
+- [SciTools/workflows `ci-template-check.yml`](https://github.com/SciTools/workflows/blob/main/.github/workflows/ci-template-check.yml)
+uses the `prompt_share()` function to remind repository developers if they are
+modifying a templated file and should consider sharing the change.
+
+All other files in this directory are the templates themselves.
+
+## Things we template
+
+- Files that all repositories should have, e.g. `CODE_OF_CONDUCT.md`.
+- Tools that will be valuable to multiple repositories, e.g. benchmarking
+scripts.
+- Files that are useful to have in a consistent format, e.g. 
+`.pre-commit-config.yaml`.
+
+Files DO NOT need to be identical - they are human-readable not 
+machine-readable, so can include whatever placeholders / optional content is
+considered appropriate.
+
+## Please contribute!
+
+This directory needs to grow. Any files you can think to template will be a 
+valuable addition.
+**Remember to update [`_templating_config.json`](_templating_config.json).**

templates/_templating_config.json

@@ -1,6 +1,7 @@
 {
   "_templating_config.json": {},
   "_templating_scripting.py": {},
+  "README.md": {},
   ".pre-commit-config.yaml": {
     "cf-units": ".pre-commit-config.yaml",
     "iris": ".pre-commit-config.yaml",

templates/_templating_scripting.py

@@ -98,12 +98,23 @@ def git_diff(*args: str) -> str:
             file_url = f"{SCITOOLS_URL}/{repo}/blob/main/{path_in_repo}"
             file_link = f"[`{path_in_repo}`]({file_url})"
             issue_body = (
-                f"The template for {file_link} has been updated.\n\n"
-                "Consider adopting these changes into the repo; "
-                "the changes can be found below.\n\n"
-                "The template file can be found in the **.github** repo: "
-                f"{template_link}\n\n"
-                "The diff between the specified file is as follows:\n\n"
+                f"The template for `{path_in_repo}` has been updated; see the "
+                "diff below. Please either:\n\n"
+                
+                "- Action this issue with a pull request applying some/all of "
+                f"these changes to `{path_in_repo}`.\n"
+                "- Close this issue if _none_ of these changes are appropriate "
+                "for this repo.\n\n"
+                "Also consider reviewing a full diff between the template and "
+                f"`{path_in_repo}`, in case other valuable shared conventions "
+                f"have previously been missed.\n\n"
+
+                "## File Links\n\n"
+                f"- The file in this repo: {file_link}\n"
+                f"- The template file in the **.github** repo: {template_link}\n\n"
+                # TODO: a link to the whole diff compared to the template?
+
+                "## Diff\n\n"
                 f"```diff\n{diff}\n```"
             )
             with NamedTemporaryFile("w") as file_write: