Contributing to Charmed HPC’s documentation¶

Contributions to Charmed HPC’s documentation are welcomed and encouraged. Please read through the following guidelines to best prepare yourself for contributing. If you have questions, feel free to ask them in the Ubuntu High-Performance Computing Matrix chat or in Charmed HPC’s GitHub Discussions.

Prerequisites¶

There are a couple prerequisites to contributing to Charmed HPC’s documentation:

GitHub Account: The Charmed HPC project uses GitHub to host its documentation. You will need an active GitHub account to report issues and provide contributions. See Creating an account on GitHub for more details.
Code of Conduct: You must read and follow the Ubuntu Code of Conduct to contributed to Charmed HPC. Maintainers reserve the right to delete or remove any contributions that do not respect the Code of Conduct.

Report an issue¶

To report an error in spelling, grammar, content, or documentation code functionality, file an issue in Charmed HPC’s bug tracker on GitHub.

Simple update¶

The easiest way to make a quick update, especially for those new to git and GitHub, is to use GitHub’s file editor through your web browser.

Large contribution¶

For larger, more involved contributions, and those familiar with git and the command line, follow the fork-and-branch process. Be sure to familiarize yourself with the Documentation structure prior to any significant work.

Test your contribution¶

To ensure that your contributions meet expectations and pass CI rules, check that they pass the repository’s tests.

Test locally¶

Install npm using the appropriate method for your operating system through one of the follow processes:

Through your preferred package manager
By following the node version manager installation process
For Ubuntu and other snap-supported Linux distributions: sudo snap install node --classic

Then install commitlint:

npm install -D @commitlint/cli @commitlint/config-conventional

Warning

Make sure to run the commitlint installation command outside of the docs directory. The commitlint installation process installs a node_modules folder that should not become part of the docs repository.

To run the tests:

Command	Usage
`make spelling`	Check for spelling errors; this command checks the HTML files in the `_build` directory. Fix any errors in the corresponding Markdown file
`make linkcheck`	Check for broken links
`make woke`	Check for non-inclusive language
`make pa11y`	Check for accessibility issues
`make vale`	Check for style guide compliance
`npx commitlint --from <start-ID> --to <end-ID> --verbose`	Check for commitlint compliance from git commit ID `<start-ID>` to commit ID `<end-ID>`

For more information on setting up the tests locally, see Automatic checks within the Canonical Starter Pack documentation.

Test through GitHub¶

If running the tests locally is not ideal, you may run them within GitHub. To do so, make sure any local changes have been pushed to your personal fork+branch and are visible from the web interface. Then, from the web interface for GitHub:

Go to the Actions tab.
Select the test of interest: Automatic docs checks or docs test
Select Run workflow within the workflows panel.
Select the relevant branch from the drop-down menu.
Select Run workflow within the drop-down.

Documentation structure¶

The documentation is written in the MyST flavor of the Markdown mark-up language. The sections are organized using the Diátaxis framework. See Canonical’s MyST syntax Guide for formatting and preferred usage guidance.