charmed-hpc · NucciTheBoss · Oct 1, 2024 · Oct 1, 2024 · Oct 1, 2024
@@ -1,34 +1,232 @@
-# Contributing
+# Contributing to the hpc-libs repository
 
-To make contributions to this charm, you'll need a working [development setup](https://juju.is/docs/sdk/dev-setup).
+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.__
 
-You can create an environment for development with `tox`:
+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](https://juju.is/docs/sdk) as it will help you
+better understand how the charm libraries are put together.
 
-```shell
-tox devenv -e integration
-source venv/bin/activate
-```
+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.
 
-## Testing
+Have any questions? Feel free to ask them in the [Ubuntu High-Performance Computing
+Matrix chat](https://matrix.to/#/#hpc:ubuntu.com).
 
-This project uses `tox` for managing test environments. There are some pre-configured environments
-that can be used for linting and formatting code when you're preparing contributions to the charm:
+### Table of Contents
 
-```shell
-tox run -e format        # update your code according to linting rules
-tox run -e lint          # code style
-tox run -e static        # static type checking
-tox run -e unit          # unit tests
-tox run -e integration   # integration tests
-tox                      # runs 'format', 'lint', 'static', and 'unit' environments
-```
+* [Using the issue tracker](#using-the-issue-tracker)
+* [Issues and Labels](#issues-and-labels)
+* [Bug Reports](#bug-reports)
+* [Enhancement Proposals](#enhancement-proposals)
+* [Pull Requests](#pull-requests)
+* [Discussions](#discussions)
+* [Code Guidelines](#code-guidelines)
+* [License](#license)
 
-## Build the charm
+## Using the issue tracker
 
-Build the charm in this git repository using:
+The issue tracker is the preferred way for tracking [bug reports](#bug-reports), [enhancement proposals](#enhancement-proposals),
+and [submitted pull requests](#pull-requests), but please follow these guidelines for the issue tracker:
 
-```shell
-charmcraft pack
-```
+* Please __do not__ use the issue tracker for personal issues and/or support requests.
+The [Discussions](#discussions) page is a better place to get help for personal support requests.
 
-<!-- You may want to include any contribution/style guidelines in this document>
+* 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](https://blog.github.com/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/)
+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](https://github.com/charmed-hpc/hpc-libs/labels).
+
+## 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__ &mdash; ensure that your issue is not being caused by either
+a semantic or syntactic error in your environment.
+
+2. __Use the GitHub issue search__ &mdash; check if the issue you are encountering has
+already been reported by someone else.
+
+3. __Check if the issue has already been fixed__ &mdash; try to reproduce your issue
+using the latest version of the charm library causing the problem.
+
+4. __Isolate the problem__ &mdash; 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 &mdash; patches, improvements, new features &mdash;
+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](https://help.github.com/articles/fork-a-repo/) the project, clone your fork,
+   and configure the remotes:
+
+   ```bash
+   # 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:
+
+   ```bash
+   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:
+
+   ```bash
+   git checkout -b <topic-branch-name>
+   ```
+
+4. Ensure that your changes pass all tests:
+
+    ```bash
+    # 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](https://www.conventionalcommits.org/en/v1.0.0/).
+   You can use Git's
+   [interactive rebase](https://help.github.com/articles/about-git-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:
+
+   ```bash
+   git pull [--rebase] upstream main
+   ```
+
+7. Push your topic branch up to your fork:
+
+   ```bash
+   git push origin <topic-branch-name>
+   ```
+
+8. [Open a Pull Request](https://help.github.com/articles/about-pull-requests/)
+    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
+
+* Adhere to the operator development best practices outlined in the [operator development styleguide](https://juju.is/docs/sdk/styleguide).
+
+### Python
+
+* Adhere to the Python code style guidelines outlined in [Python Enhancement Proposal 8](https://pep8.org/).
+
+* Adhere to the Python docstring conventions outlined in
+[Python Enhancement Proposal 257](https://www.python.org/dev/peps/pep-0257/).
+  * *Docstrings must follow the
+  [Google docstring format](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings)*.
+license
+
+## 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](https://www.apache.org/licenses/LICENSE-2.0.html).
@@ -1,26 +1,74 @@
-<!--
-Avoid using this README file for information that is maintained or published elsewhere, e.g.:
+# hpc-libs
 
-* metadata.yaml > published on Charmhub
-* documentation > published on (or linked to from) Charmhub
-* detailed contribution guide > documentation or CONTRIBUTING.md
+[![hpc-libs tests](https://github.com/charmed-hpc/hpc-libs/actions/workflows/ci.yaml/badge.svg)](https://github.com/charmed-hpc/hpc-libs/actions/workflows/ci.yaml)
+[![Release](https://github.com/charmed-hpc/hpc-libs/actions/workflows/release-libs.yaml/badge.svg)](https://github.com/charmed-hpc/hpc-libs/actions/workflows/release-libs.yaml)
+![GitHub License](https://img.shields.io/github/license/charmed-hpc/hpc-libs)
+[![Matrix](https://img.shields.io/matrix/ubuntu-hpc%3Amatrix.org?logo=matrix&label=ubuntu-hpc)](https://matrix.to/#/#hpc:ubuntu.com)
 
-Use links instead.
--->
+A collection of charm libraries for authoring HPC charms 📖🖋️
 
-# hpc-libs
+The hpc-libs charm libraries are used within the [Juju](https://juju.is) charms that compose
+Charmed HPC. They are standalone libraries, and should be managed
+as charm libraries, with installation via `charmcraft fetch-lib ...`, after which they may be
+imported and used as normal Python modules. The current charm libraries in hpc-libs include:
+
+* `is_container` - a library for detecting the virtualization environment the charm is running within.
+* `slurm_ops` - a library for managing Slurm cluster operations via snap or systemd.
+
+## ✨ Getting Started
+
+Each charm library contains documentation and usage information in its module-level docstring.
+Pretty documentation, along with installation instructions, can be viewed on Charmhub:
+
+* [`is_container` documentation](https://charmhub.io/hpc-libs/libraries/is_container)
+* [`slurm_ops` documentation](https://charmhub.io/hpc-libs/libraries/slurm_ops)
+
+## 🤔 What's next?
+
+If you want to learn more about all the things you can do with the hpc-libs charm libraries,
+or have any further questions on what you can do with the charm libraries, here are some
+further resources for you to explore:
+
+* [Open an issue](https://github.com/charmed-hpc/hpc-libs/issues/new?title=ISSUE+TITLE&body=*Please+describe+your+issue*)
+* [Ask a question on Github](https://github.com/orgs/charmed-hpc/discussions/categories/q-a)
+
+## 🛠️ Development
+
+This project uses [tox](https://tox.wiki) as its command runner, which provides
+some useful commands that will help you while hacking on hpc-libs:
+
+```shell
+tox run -e fmt     # Apply formatting standards to code.
+tox run -e lint    # Check code against coding style standards.
+tox run -e static  # Run static type checks.
+tox run -e unit    # Run unit tests.
+```
+
+To run the hpc-libs integration tests, you'll need to have both
+[gambol](https://github.com/nuccitheboss/gambol) and [LXD](https://ubuntu.com/lxd) installed
+on your machine:
+
+```shell
+tox run -e integration  # Run integration tests.
+```
 
-Charmhub package name: operator-template
-More information: https://charmhub.io/hpc-libs
+If you're interested in contributing your work to hpc-libs,
+take a look at our [contributing guidelines](./CONTRIBUTING.md) for further details.
 
-Describe your charm in one or two sentences.
+## 🤝 Project and community
 
-## Other resources
+The hpc-libs charm libraries are a project of the [Ubuntu High-Performance Computing community](https://ubuntu.com/community/governance/teams/hpc).
+Interested in contributing bug fixes, new editors, documentation, or feedback? Want to join the Ubuntu HPC community? You’ve come to the right place 🤩
 
-<!-- If your charm is documented somewhere else other than Charmhub, provide a link separately. -->
+Here’s some links to help you get started with joining the community:
 
-- [Read more](https://example.com)
+* [Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct)
+* [Contributing guidelines](./CONTRIBUTING.md)
+* [Join the conversation on Matrix](https://matrix.to/#/#hpc:ubuntu.com)
+* [Get the latest news on Discourse](https://discourse.ubuntu.com/c/hpc/151)
+* [Ask and answer questions on GitHub](https://github.com/orgs/charmed-hpc/discussions/categories/q-a)
 
-- [Contributing](CONTRIBUTING.md) <!-- or link to other contribution documentation -->
+## 📋 License
 
-- See the [Juju SDK documentation](https://juju.is/docs/sdk) for more information about developing and improving charms.
+The hpc-libs charm libraries are free software, distributed under the Apache Software License, version 2.0.
+See the [Apache-2.0 LICENSE](./LICENSE) file for further details.