From 28ffbbf12a60bb6264fe016e3f930e90d6344578 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Juli=C3=A1n=20Espina?= Date: Tue, 17 Dec 2024 19:28:09 -0600 Subject: [PATCH] docs: add README.md and CONTRIBUTE.md --- CONTRIBUTE.md | 230 ++++++++++++++++++++++++++++++++++ README.md | 53 ++++++++ tests/unit/test_interfaces.py | 2 +- 3 files changed, 284 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTE.md create mode 100644 README.md diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 0000000..590289e --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,230 @@ +# Contributing to the filesystem-client-operator repository + +Do you want to contribute to the repository? 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](https://juju.is/docs/sdk) as it will help you +better understand how the charm is put together. + +Following these guidelines helps you communicate that you respect the maintainers +of the repository. 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](https://matrix.to/#/#hpc:ubuntu.com). + +### Table of Contents + +* [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) + +## Using the issue tracker + +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: + +* 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. + +* Please __do not__ derail or troll issues. Keep the discussion on track and have respect for the other +users/contributors of this repository. + +* 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 this repository 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 this repository 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. + +* `Statues: 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/filesystem-client-operator/labels). + +## Bug Reports + +A bug is a *demonstrable problem* that is caused by errors in the repository. +Good bug reports make the repository better, so +thank you for taking the time to report issues! + +Guidelines for reporting bugs with the repository: + +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 repository. + +4. __Isolate the problem__ — the more pinpointed the issue with the repository +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 repository. + +## Enhancement Proposals + +The Charmed HPC core developers may already know what they want to add to the repository, +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 the repository. Also, please +know that spamming the maintainers to incorporate something you want into the repository +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 the repository! 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 repository: + +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//filesystem-client-operator.git + + # Navigate to the newly cloned directory + cd filesystem-client-operator + + # Assign the original repo to a remote called "upstream" + git remote add upstream https://github.com/charmed-hpc/filesystem-client-operator.git + ``` + +2. If you cloned a while ago, pull the latest changes from the upstream filesystem-client-operator 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 + ``` + +4. Ensure that your changes pass all tests: + + ```bash + # Apply formatting standards to code. + just fmt + + # Check code against coding style standards. + just lint + + # Run type checking. + just typecheck + + # Run unit tests. + just unit + + # Run integration tests. + just 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 + ``` + +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 + +By contributing your code to the repository, you agree to license your contribution under the +[Apache Software License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). diff --git a/README.md b/README.md new file mode 100644 index 0000000..06e3d9c --- /dev/null +++ b/README.md @@ -0,0 +1,53 @@ +# Filesystem client operator + +A [Juju](https://juju.is) operator for mounting filesystems. + +[![Charmhub Badge](https://charmhub.io/filesystem-client/badge.svg)](https://charmhub.io/filesystem-client) +[![CI](https://github.com/charmed-hpc/filesystem-client-operator/actions/workflows/ci.yaml/badge.svg)](https://github.com/charmed-hpc/filesystem-client-operator/actions/workflows/ci.yaml/badge.svg) +[![Publish](https://github.com/charmed-hpc/filesystem-client-operator/actions/workflows/publish.yaml/badge.svg)](https://github.com/charmed-hpc/filesystem-client-operator/actions/workflows/publish.yaml/badge.svg) +[![Matrix](https://img.shields.io/matrix/ubuntu-hpc%3Amatrix.org?logo=matrix&label=ubuntu-hpc)](https://matrix.to/#/#ubuntu-hpc:matrix.org) + + +The filesystem client operator requests and mounts exported filesystems on virtual machines. + +## ✨ Getting started + +1. Deploy a filesystem provider (microceph with ceph-fs in this case), filesystem-client, and a machine to mount the filesystem on: + +```shell +juju add-model store +juju deploy -n 3 microceph \ + --channel latest/edge \ + --storage osd-standalone='2G,3' \ + --constraints="virt-type=virtual-machine root-disk=10G mem=4G" +juju deploy ceph-fs --channel latest/edge +juju deploy filesystem-client --channel latest/edge \ + --config mountpoint='/scratch' \ + --config noexec=true +juju deploy ubuntu --base ubuntu@24.04 --constraints virt-type=virtual-machine +``` + +2. Integrate everything, and that's it! + +```shell +juju integrate microceph:mds ceph-fs:ceph-mds +juju integrate filesystem-client:filesystem ceph-fs:filesystem +juju integrate ubuntu:juju-info data:juju-info +``` + +## 🤝 Project and community + +The filesystem client operator is a project of the [Ubuntu High-Performance Computing community](https://ubuntu.com/community/governance/teams/hpc). +It is an open source project that is welcome to community involvement, contributions, suggestions, fixes, and +constructive feedback. Interested in being involved with the development of the filesystem client operator? Check out these links below: + +* [Join our online chat](https://matrix.to/#/#ubuntu-hpc:matrix.org) +* [Contributing guidelines](./CONTRIBUTING.md) +* [Code of conduct](https://ubuntu.com/community/ethos/code-of-conduct) +* [File a bug report](https://github.com/charmed-hpc/filesystem-client-operator/issues) +* [Juju SDK docs](https://juju.is/docs/sdk) + +## 📋 License + +The filesystem client operator is free software, distributed under the +Apache Software License, version 2.0. See the [LICENSE](./LICENSE) file for more information. diff --git a/tests/unit/test_interfaces.py b/tests/unit/test_interfaces.py index 077f3a0..212497d 100644 --- a/tests/unit/test_interfaces.py +++ b/tests/unit/test_interfaces.py @@ -29,7 +29,7 @@ class FsClientCharm(CharmBase): - """Mock CephFS client charm for unit tests.""" + """Mock FS client charm for unit tests.""" def __init__(self, *args, **kwargs) -> None: super().__init__(*args, **kwargs)