Attention
Advance Notice: Bessemer will be retired at the end of the day on Friday 31st October 2025.
Contributing
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.
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 ofsheffield_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 tosheffield_hpc
until the referenced commit is available in the upstreamhpc-examples/main
branch.