Contributing to Charmed HPC’s code

Charmed HPC is a open source project and welcomes community contributions. Please read through the following guidelines to best prepare yourself for making contributions. If you have questions, feel free to ask them in the Ubuntu High-Performance Computing Matrix chat or in Charmed HPC’s GitHub Discussions.

Report an issue

To report an issue or bug, file an issue in the appropriate Charmed HPC GitHub Organization repository’s issue tracker. If you are unsure which repository the issue should belong to, share the issue in Charmed HPC’s GitHub Discussions.

When reporting a bug, please:

  • Validate your issue — ensure that your issue is not being caused by either a semantic or syntactic error in your environment.

  • Use the GitHub issue search — check if the issue you are encountering has already been reported by someone else.

  • Check if the issue has already been fixed — try to reproduce your issue using the latest revision of the repository.

  • Isolate the problem — the more pinpointed the issue, the easier it is to fix.

  • Provide context — your current environment, error reproduction in other environments, specific commands and actions to produce the error, and expected outcome.

Enhancement proposals

While Charmed HPC’s maintainers will often already have a plan for upcoming features, we welcome community ideas and potential improvements. Charmed HPC’s GitHub Discussions is a good place for discussing open-ended questions, and more focused proposals can be created within a relevant repository’s issue tracker.

Pull requests

Good pull requests — patches, improvements, new features — are a huge help.

Ask first before embarking on any significant pull request such as implementing new features, refactoring methods, or incorporating new libraries. Otherwise, you risk spending a lot of time working on a contribution that Charmed HPC’s maintainers may be unable to include. For trivial changes and small contributions, you may feel free to open a pull request.

Adhering to the following process is the best way to have your contribution accepted:

  1. Fork the project, clone your fork, and configure the remotes:

    # Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/<repository>.git

# Navigate to the newly cloned directory
cd <repository>

# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/charmed-hpc/<repository>.git

  2. If you cloned a while ago, pull the latest changes from the upstream repository:

    git checkout main
git pull upstream main

  3. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:

    git checkout -b <topic-branch-name>

  4. Ensure that your changes pass all tests.

    The tests may differ for different repositories. See the corresponding repository’s CONTRIBUTING file for details on the appropriate tests.

  5. Sign and commit and your changes in logical chunks to your topic branch, using Conventional Commits.

    To set up GPG or SSH key signing with git, see GitHub’s commit signature verification documentation

  6. Locally rebase the upstream development branch into your topic branch:

    git pull --rebase upstream main

  7. Push your topic branch up to your fork:

    git push origin <topic-branch-name>

  8. Open a Pull Request with a clear title and description against the main branch. Your pull request should also be focused and not contain commits that are not related to what you are contributing.

  9. Conditionally, open a corresponding Pull Request on the docs repository, following the charmed-hpc/docs CONTRIBUTING.md guidelines, if you are making user-facing changes.

Further resources

See the below resources for further guidance and useful references: