Skip to content

Latest commit

 

History

History
232 lines (161 loc) · 9.13 KB

CONTRIBUTING.md

File metadata and controls

232 lines (161 loc) · 9.13 KB
Raw

Contributing to the hpc-libs repository

Do you want to contribute to the hpc-libs charm libraries? You've come to the right place then! Here is how you can get involved.

Please take a moment to review this document so that the contribution process will be easy and effective for everyone. Also, please familiarise yourself with the Juju SDK as it will help you better understand how the charm libraries are put together.

Following these guidelines helps you communicate that you respect the maintainers managing the libraries. In return, they will reciprocate that respect while addressing your issue or assessing your submitted changes and/or features.

Have any questions? Feel free to ask them in the Ubuntu High-Performance Computing Matrix chat.

Table of Contents

Using the issue tracker

The issue tracker is the preferred way for tracking bug reports, enhancement proposals, and submitted pull requests, but please follow these guidelines for the issue tracker:

  • Please do not use the issue tracker for personal issues and/or support requests. The Discussions page is a better place to get help for personal support requests.

  • Please do not derail or troll issues. Keep the discussion on track and have respect for the other users/contributors of the hpc-libs charm libraries.

  • Please do not post comments consisting solely of "+1", ":thumbsup:", or something similar. Use GitHub's "reactions" feature instead.

    • The maintainers of the hpc-libs charm libraries reserve the right to delete comments that violate this rule.

  • Please do not repost or reopen issues that have been closed. Please either submit a new issue or browser through previous issues.

    • The maintainers of the hpc-libs charm libraries reserve the right to delete issues that violate this rule.

Issues and Labels

The issue tracker uses a variety of labels to help organize and identify issues. Here is a list of some of these labels, and how the maintainers of the repository use them:

  • Type: Bug - Issues reported in the source code that either produce errors or unexpected behavior.

  • Status: Confirmed - Issues marked Type: Bug that have be confirmed to be reproducible on a separate system.

  • Type: Documentation - Issues for improving or updating the documentation. Can also be used for pull requests.

  • Type: Refactor - Issues that pertain to improving the existing code base.

  • Type: Idea Bank - Issues that pertain to proposing potential improvements to the code base.

  • Type: Enhancement - Issues marked as an agreed upon enhancement to the code base. Can also be used for pull requests.

  • Status: Help wanted - Issues where we need help from the greater open source community to solve.

For a complete look at this repository's labels, see the project labels page.

Bug Reports

A bug is a demonstrable problem that is caused by errors in the hpc-libs charm libraries. Good bug reports make the charm libraries better, so thank you for taking the time to report issues!

Guidelines for reporting bugs with the charm libraries:

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

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

  3. Check if the issue has already been fixed — try to reproduce your issue using the latest version of the charm library causing the problem.

  4. Isolate the problem — the more pinpointed the issue with the charm libraries is, the easier it is to fix.

A good bug report should not leave others needing to chase you for more information. Some common questions you should answer in your report include:

  • What is your current environment?
  • Were you able to reproduce the issue in another environment?
  • Which commands/actions/configuration options/etc produce the issue?
  • What was your expected outcome?

Please try to be as detailed as possible in your report. All these details will help the maintainers quickly fix issues with the charm libraries.

Enhancement Proposals

The Charmed HPC core developers may already know what they want to add to the hpc-libs charm libraries, but they are always open to new ideas and potential improvements. GitHub Discussions is a good place for discussing open-ended questions that pertain to the entire Charmed HPC project, but more focused enhancement proposal discussions can start within the issue tracker.

Please note that not all proposals may be incorporated into the charm libraries. Also, please know that spamming the maintainers to incorporate something you want into the charm libraries will not improve the likelihood of being implemented; it may result in you receiving a temporary ban from the repository.

Pull Requests

Good pull requests — patches, improvements, new features — are a huge help. Pull requests should remain focused and not contain commits not related to what you are contributing.

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 something that the Charmed HPC core developers may not want to merge into the hpc-libs charm libraries! For trivial changes, or contributions that do not require a large amount of time, you can go ahead and open a pull request.

Adhering to the following process is the best way to get your contribution accepted into the charm libraries:

  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>/hpc-libs.git

# Navigate to the newly cloned directory
cd hpc-libs

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

  2. If you cloned a while ago, pull the latest changes from the upstream hpc-libs 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:

    # Apply formatting standards to code.
tox run -e fmt

# Check code against coding style standards.
tox run -e lint

# Run static type checks.
tox run -e static

# Run unit tests.
tox run -e unit

# Run integration tests.
tox run -e integration

  5. Commit your changes in logical chunks to your topic branch.

    Our project follows the Conventional Commits specification, version 1.0.0. You can use Git's interactive rebase feature to tidy up your commits before pushing them to your origin branch.

  6. Locally merge (or 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.

Discussions

GitHub Discussions is a great place to connect with other Charmed HPC users to discuss potential enhancements, ask questions, and resolve issues. Charmed HPC users should remain respectful of each other. Discussion moderators reserve the right to suspend discussions and/or delete posts that do not follow this rule.

Code guidelines

The following guidelines must be adhered to if you are writing code to be merged into the main code base:

Juju and charmed operators

Python

License

By contributing your code to the hpc-libs charm libraries, you agree to license your contribution under the Apache Software License, version 2.0.