From 5b2c3ea76af329e2e81ce637836f3b4afec50136 Mon Sep 17 00:00:00 2001 From: Jason Nucciarone <40342202+NucciTheBoss@users.noreply.github.com> Date: Wed, 26 Jul 2023 05:53:49 -0700 Subject: [PATCH] Add README & CONTRIBUTING (#11) * feat: Add contrib guidelines * feat: Add README * cleanup: Add note about using Juju 3.x --- .../ISSUE_TEMPLATE/enhancement_proposal.yml | 17 -- CONTRIBUTING.md | 204 ++++++++++++++++++ README.md | 54 +++++ 3 files changed, 258 insertions(+), 17 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/enhancement_proposal.yml create mode 100644 CONTRIBUTING.md create mode 100644 README.md diff --git a/.github/ISSUE_TEMPLATE/enhancement_proposal.yml b/.github/ISSUE_TEMPLATE/enhancement_proposal.yml deleted file mode 100644 index ca024ec..0000000 --- a/.github/ISSUE_TEMPLATE/enhancement_proposal.yml +++ /dev/null @@ -1,17 +0,0 @@ -name: Enhancement Proposal -description: File an enhancement proposal -labels: ["Type: Enhancement", "Status: Triage"] -body: - - type: markdown - attributes: - value: > - Thanks for taking the time to fill out this enhancement proposal! Before submitting your proposal, please make - sure there isn't a pre-existing similar proposal. If there is, please join that discussion instead. - - type: textarea - id: enhancement-proposal - attributes: - label: Enhancement Proposal - description: > - Describe the enhancement you would like to see in as much detail as needed. - validations: - required: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b47b470 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,204 @@ +# Contributing to slurmrestd-operator + +Do you have something that you wish to contribute to slurmrestd-operator? __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](https://juju.is/docs/sdk) as it will help +you better understand how slurmrestd-operator works and is developed. + +Following these guidelines helps you communicate that you respect the developers managing and developing slurmrestd-operator. +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](https://matrix.to/#/#ubuntu-hpc:matrix.org). + +### Table of Contents + +* [Using the issue tracker](#using-the-issue-tracker) +* [Issues and Labels](#issues-and-labels) +* [Bug Reports](#bug-reports) +* [Feature Requests](#feature-requests) +* [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), [feature requests](#feature-requests), +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 slurmrestd-operator. + +* 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 slurmrestd-operator 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 slurmrestd-operator reserve the right to delete issues that violate this rule. + +## Issues and Labels + +The slurmrestd-operator 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 slurmrestd-operator use them: + +* `Type: Bug` - Issues reported in the slurmrestd-operator 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 slurmrestd-operator's documentation. +Can also be used for pull requests. + +* `Type: Refactor` - Issues that pertain to improving the existing slurmrestd-operator code base. + +* `Type: Idea Bank` - Issues that pertain to proposing potential improvement to slurmrestd-operator. + +* `Type: Enchancement` - Issues marked as an agreed upon enhancement to slurmrestd-operator. Can also be used for pull requests. + +* `Statues: Help wanted` - Issues where we need help from the greater slurmrestd-operator community to solve. + +For a complete look at slurmrestd-operator's labels, see the +[project labels page](https://github.com/omnivector-solutions/slurmrestd-operator/labels). + +## Bug Reports + +A bug is a *demonstrable problem* that is caused by slurmrestd-operator. Good bug reports make slurmrestd-operator more robust, so thank +you for taking the time to report issues in the source code! + +Guidelines for reporting bugs in slurmrestd-operator: + +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 slurmrestd-operator repository. + +4. __Isolate the problem__ — the more pinpointed the issue is, the easier time the slurmrestd-operator 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 +slurmrestd-operator already know the features they want to incorporate into slurmrestd-operator, 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 slurmrestd-operator. 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 slurmrestd-operator 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 slurmrestd-operator'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](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//slurmrestd-operator.git + # Navigate to the newly cloned directory + cd slurmrestd-operator + # Assign the original repo to a remote called "upstream" + git remote add upstream https://github.com/omnivector-solutions/slurmrestd-operator.git + ``` + +2. If you cloned a while ago, pull the latest changes from the upstream slurmrestd-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 + tox run -e fmt + tox run -e lint + tox run -e unit + tox run -e integration + ``` + +5. Commit your changes in logical chunks. Please adhere to these [git commit + message guidelines](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) + or your code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +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. + +__IMPORTANT__: By submitting a patch, improvement, or new feature, you agree to allow the maintainers of slurmrestd-operator to +license your contributions under the terms of the [Apache Software License, version 2.0](./LICENSE). + +## Discussions + +GitHub's discussions are a great place to connect with other users of slurmrestd-operator as well as discuss potential +features and resolve personal support questions. It is expected that the users of slurmrestd-operator 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 slurmrestd-operator code base: + +### Juju & 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/). + * *slurmrestd-operator docstrings 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 slurmrestd-operator, 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..78b31c4 --- /dev/null +++ b/README.md @@ -0,0 +1,54 @@ +
+ +# slurmrestd operator + +A [Juju](https://juju.is) operator for slurmrestd - the REST API interface to [SLURM](https://slurm.schedmd.com/overview.html). + +[![Charmhub Badge](https://charmhub.io/slurmrestd/badge.svg)](https://charmhub.io/slurmrestd) +[![CI](https://github.com/omnivector-solutions/slurmrestd-operator/actions/workflows/ci.yaml/badge.svg)](https://github.com/omnivector-solutions/slurmrestd-operator/actions/workflows/ci.yaml/badge.svg) +[![Release](https://github.com/omnivector-solutions/slurmrestd-operator/actions/workflows/release.yaml/badge.svg)](https://github.com/omnivector-solutions/slurmrestd-operator/actions/workflows/release.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) + +
+ +## Features + +The slurmrestd operator provides the slurmrestd service. This operator provides a REST API for interfacing with the SLURM +workload manager. Rather than interfacing with SLURM via cluster head nodes, slurmrestd enables submitting batch jobs +via HTTP requests over a network. + +## Usage + +This operator should be used with Juju 3.x or greater. + +#### Deploy a minimal Charmed SLURM cluster with slurmrestd + +```shell +$ juju deploy slurmrestd --channel edge +$ juju deploy slurmctld --channel edge +$ juju deploy slurmd --channel edge +$ juju deploy slurmdbd --channel edge +$ juju deploy mysql --channel 8.0/stable +$ juju deploy mysql-router slurmdbd-mysql-router --channel 8.0/stable +$ juju integrate slurmctld:slurmrestd slurmrestd:slurmrestd +$ juju integrate slurmctld:slurmd slurmd:slurmd +$ juju integrate slurmdbd-mysql-router:backend-database mysql:database +$ juju integrate slurmdbd:database slurm-mysql-router:database +$ juju integrate slurmctld:slurmdbd slurmdbd:slurmdbd +``` + +## Project & Community + +The slurmrestd operator is a project of the [Ubuntu HPC](https://discourse.ubuntu.com/t/high-performance-computing-team/35988) +community. 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 slurmrestd 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/omnivector-solutions/slurmrestd-operator/issues) +* [Juju SDK docs](https://juju.is/docs/sdk) + +## License + +The slurmrestd operator is free software, distributed under the Apache Software License, version 2.0. See the [LICENSE](./LICENSE) file for more information.