Contributing

When contributing batch submission examples, use the batch template guide alongside the Style Guide.

If you are working on contributing to the documentation, here is a possible checklist of tasks to complete:

  • Identify the scope and purpose of the documentation.
    • What topics will be covered?

    • What level of detail is required?

    • Consider consulting with other contributors or users to gather feedback and ensure that the documentation meets their needs.

  • Create a new branch or fork of the codebase to make your changes.
    • Make sure to name the branch or fork appropriately to reflect the purpose of the changes

    • Naming convention is author initials (xyz in examples below), category, issue number (if relevant), descriptive name:

    • Category

      Example

      Enhancement

      xyz-en-1752-descriptive-name

      Fix

      xyz-fx-1752-descriptive-name

      Bug

      xyz-bg-1752-descriptive-name

  • Write the documentation in a clear, concise, and consistent style.
    • Use headings, lists, and other formatting tools to make the information easy to read and understand.

    • Consider including screenshots or diagrams to illustrate complex concepts.

    • Follow existing conventions such as placeholder usernames or implementing tab order from the newest to oldest HPC cluster.

  • Add the documentation to the appropriate location in the codebase.
    • Make sure to use the correct file format (e.g., Markdown, reStructuredText).

    • Follow existing conventions for organising documentation.

    • Make sure to use import files to deduplicate content where possible.

  • Add links to the documentation from relevant parts of the site, such as the admin dashboard or help pages.
    • Make sure that the links are clear and easy to find.

  • Update existing pages to reference any new documentation.
    • Update any relevant index pages or tables of contents to include the new documentation.

    • Update the README or other project documentation to reflect the changes you have made.

  • Test the documentation to ensure that it is accurate and up-to-date.
    • Try following the instructions yourself to see if they are clear and complete.

    • Ask other contributors or users to review the documentation and provide feedback.

    • Build the documentation on your local machine to check it does so correctly.

  • Create a pull request on GitHub.
    • Make sure to describe the changes you have made in the PR description.

    • Be sure to reference any issues or discussion threads that are related to the changes.

    • Mark a PR as draft until it is ready for review.

    • Choose appropriate reviewers for the changes you have made.

    • Monitor the PR for feedback and address any issues or concerns raised by other contributors.

    • Once the changes have been reviewed and approved, merge the PR into the main codebase.

Guidance dates

Section guidance last updated: 27 October 2026

For a short guide reviewed as a whole, place this field at the top of the page, before labels, includes and the title:

:guidance_last_updated: 2026-10-27

For a large page reviewed section by section, place this directive immediately below a heading one level below the page title:

Storage guidance
----------------

.. section-guidance-updated:: 2026-10-27

A section date covers that section and its subsections. Review the whole section before updating its date; do not refresh a page-wide date for a partial review. Deeper headings do not have separate dates. A small edit need not change the date when the surrounding guidance has not been reviewed.

Maintain dates in the same PR as substantive changes to instructions, commands or examples. When shared instructions change, update the dates on affected guides or reviewed sections rather than adding page metadata to shared snippets. Metadata and formatting changes alone do not count. Navigation-only indexes, newsletters and historical or decommissioned records remain undated; substantive guides named index.rst can have dates. Pending reviews retain their earlier date until substantive changes merge.

How to Make Changes to hpc-examples and Reflect Them in sheffield_hpc

If you make changes inside the hpc-examples submodule (e.g. editing or adding a script), follow these steps to ensure both repositories stay in sync:

First, commit and push the changes in hpc-examples:

cd hpc-examples
git add <file>
git commit -m "Add/update example script"
git push

Wait for the hpc-examples pull request to be reviewed, approved, and merged into main before updating the submodule pointer in sheffield_hpc:

cd ..
git add hpc-examples
git commit -m "Update hpc-examples submodule pointer"
git push

This ensures sheffield_hpc tracks a public, stable commit of hpc-examples.

Important

When updating the submodule pointer to hpc-examples:

  • Only reference commits that have already been merged into the main branch.

  • Never commit a pointer to a branch-only or unpublished commit — this will cause submodule fetch failures in GitHub Actions workflows and for collaborators cloning the repo.

  • Local changes to hpc-examples will build and render correctly within your local clone of sheffield_hpc, even before they are pushed or merged.

  • You may temporarily point to a local commit of hpc-examples for testing, but do not push that pointer to sheffield_hpc until the referenced commit is available in the upstream hpc-examples/main branch.