Skip to content

Latest commit

 

History

History
205 lines (143 loc) · 9.4 KB

CONTRIBUTING.md

File metadata and controls

205 lines (143 loc) · 9.4 KB
Raw

Contributing to storage-libs

Do you have something that you wish to contribute to storage-libs? If so, here is how you can help!

Please take a moment to review this document so that the contribution process will be easy and effective for everyone involved. Also, please familiarise yourself with the Juju SDK documentation as it will help you better understand how storage-libs works and is developed.

Following these guidelines helps you communicate that you respect the developers managing and developing storage-libs. In return, they should reciprocate that respect while they are addressing your issue or assessing your submitted patches and features.

Have any questions? Feel free to ask them in the Ubuntu HPC Matrix space.

Table of Contents

Using the issue tracker

The issue tracker is the preferred way for tracking bug reports, feature requests, 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 storage-libs.

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

    • The maintainers of storage-libs 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 storage-libs reserve the right to delete issues that violate this rule.

Issues and Labels

The storage-libs 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 storage-libs use them:

  • Type: Bug - Issues reported in the storage-libs 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 storage-libs's documentation. Can also be used for pull requests.

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

  • Type: Idea Bank - Issues that pertain to proposing potential improvement to storage-libs.

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

  • Statues: Help wanted - Issues where we need help from the greater storage-libs community to solve.

For a complete look at storage-libs's labels, see the project labels page.

Bug Reports

A bug is a demonstrable problem that is caused by storage-libs. Good bug reports make storage-libs more robust, so thank you for taking the time to report issues in the source code!

Guidelines for reporting bugs in storage-libs:

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

  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 main in the storage-libs repository.

  4. Isolate the problem — the more pinpointed the issue is, the easier time the storage-libs developers will have fixing it.

A good bug report should not leave others needing to chase you for more information. Please try to be as detailed as possible in your report. What is your environment? What steps will reproduce the issue? What operating system are you experiencing the problem on? Have you had the same results on a different operating system? What would you expect to be the outcome? All these details will help the developers fix any potential bugs.

Feature Requests

All feature requests should be posted to GitHub Discussions and tagged as Type: Idea Bank. The maintainers of storage-libs already know the features they want to incorporate into storage-libs, but they are always open to new ideas and potential improvements. GitHub Discussions is the best place to post these types of requests because it allows for feedback from the entire community and does not bloat the issue tracker. Please note that not all feature requests will be incorporated into storage-libs. Also, feature requests posted on the issue tracker will be tagged as Type: Invalid and closed. Lastly, please note that spamming the maintainers to incorporate a feature you want into storage-libs will not improve its 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. These pull requests should remain focused in scope and should not contain unrelated commits.

Ask first before embarking on any significant pull request (e.g. implementing new features, refactoring code, incorporating a new test environment provider, etc.), otherwise you risk spending a lot of time working on something that storage-libs's developers might not want to merge into the project! For trivial things, or things that do not require a lot of your time, you can go ahead and make a pull request.

Adhering to the following process is the best way to get your work included in the project:

  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>/storage-libs.git
# Navigate to the newly cloned directory
cd storage-libs
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/canonical/storage-libs.git

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

    tox run -e fmt
tox run -e lint
tox run -e unit

  5. Commit your changes in logical chunks. Please adhere to these git commit message guidelines or your code is unlikely be merged into the main project. Use Git's interactive rebase feature to tidy up your commits before making them public.

  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.

IMPORTANT: By submitting a patch, improvement, or new feature, you agree to allow the maintainers of storage-libs to license your contributions under the terms of the Apache Software License, version 2.0, and you agree to sign Canonical's contributor license agreement

Discussions

GitHub's discussions are a great place to connect with other users of storage-libs as well as discuss potential features and resolve personal support questions. It is expected that the users of storage-libs 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 storage-libs code base:

Juju & Operators

Python

License & CLA

By contributing your code to storage-libs, you agree to license your contribution under the Apache Software License, version 2.0, and you agree to sign Canonical's contributor license agreement.