From a917458422ad292ca7ccbe40cc677dc6835fdf51 Mon Sep 17 00:00:00 2001 From: "Jason C. Nucciarone" Date: Fri, 9 Aug 2024 13:20:10 -0400 Subject: [PATCH] docs: update contributing guidelines - Revise intro and expand HPC. - Replace "Feature Requests" section with "Enhancement Proposals" - Update using the issue tracker section - Revise Bug Reports section to be more clear. Copied from old repo. - Revise Pull Requests - Update commit changes to mention using Conventional Commit Standards - Revise Dicussions section - Add section justifying the use of the monorepo. Signed-off-by: Jason C. Nucciarone --- CONTRIBUTING.md | 164 +++++++++++++++++++++++++++++++----------------- 1 file changed, 105 insertions(+), 59 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74e15d2..ee0976d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,23 +1,26 @@ # Contributing to the slurm-charms repository -Do you have something that you wish to contribute to the repository? __If so, here is how you can help!__ +Do you want to contribute to the Slurm charms? 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 -involved. Also, please familiarise yourself with the [Juju SDK documentation](https://juju.is/docs/sdk) as it will help -you better understand how the charms work and are developed. +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 Slurm charms are put together. -Following these guidelines helps you communicate that you respect the developers managing and developing the repository. -In return, they should reciprocate that respect while they are addressing your issue or assessing your submitted -patches and features. +Following these guidelines helps you communicate that you respect the maintainers +managing the Slurm charms. 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 HPC Matrix space](https://matrix.to/#/#ubuntu-hpc:matrix.org). +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) -* [Feature Requests](#feature-requests) +* [Enhancement Proposals](#enhancement-proposals) * [Pull Requests](#pull-requests) * [Discussions](#discussions) * [Code Guidelines](#code-guidelines) @@ -32,16 +35,18 @@ and [submitted pull requests](#pull-requests), but please follow these guideline 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 the repository. +users/contributors of the Slurm charms. * 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. + * The maintainers of the Slurm charms 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. + * The maintainers of Slurm charms reserve the right to delete issues + that violate this rule. ## Issues and Labels @@ -68,51 +73,62 @@ For a complete look at this repository's labels, see the ## Bug Reports -A bug is a *demonstrable problem* that is caused by any of the charms on the repository. Good bug reports -make the charms more robust, so thank you for taking the time to report issues in the source code! +A bug is a *demonstrable problem* that is caused by errors in the Slurm charms. +Good bug reports make the Slurm charms better, so +thank you for taking the time to report issues! -Guidelines for reporting bugs in slurm-charms: +Guidelines for reporting bugs with the Slurm charms: -1. __Validate your testlet__ — ensure that your issue is not being caused by either a semantic or syntactic -error in your testlet's code. +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. +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 commit to -the `main` branch in the repository. +3. __Check if the issue has already been fixed__ — try to reproduce your issue +using the latest version of the Slurm charms. -4. __Isolate the problem__ — the more pinpointed the issue is, the easier time the developers will have fixing it. +4. __Isolate the problem__ — the more pinpointed the issue with the Slurm chharms +is, the easier it is to fix. 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 -the project already know the features they want to incorporate into it, 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 the code base. 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 any of the charms will not improve its likelihood of being implemented; it may result in you receiving -a temporary ban from the repository. +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 Slurm charms. + +## Enhancement Proposals + +The Charmed HPC core developers may already know what they want to add to the Slurm charms, +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 discussion can start within the issue +tracker. + +Please note that not all proposals may be incorporated into the documentation. Also, please +know that spamming the maintainers to incorporate something you want into the documentation +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. These pull requests should -remain focused in scope and should not contain unrelated commits. +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 (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 the maintainers 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. +__Ask first__ before embarking on any __significant__ pull request such as add new sections, +changing the layout, or heavily revising existing sections; otherwise, you risk spending a +lot of time working on something that Charmed HPC's maintainers may not want to merge into the +documentation! For trivial changes, or contributions that do not require a large amount of 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: +Adhering to the following process is the best way to get your contribution accepted into +Charmed HPC's documentation: 1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your fork, and configure the remotes: @@ -120,8 +136,10 @@ included in the project: ```bash # Clone your fork of the repo into the current directory git clone https://github.com//slurm-charms.git + # Navigate to the newly cloned directory cd slurm-charms + # Assign the original repo to a remote called "upstream" git remote add upstream https://github.com/charmed-hpc/slurm-charms.git ``` @@ -143,17 +161,29 @@ included in the project: 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 type checking. + tox run -e type + + # Run unit tests. tox run -e unit + + # Run integration tests. 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. +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: @@ -170,20 +200,36 @@ included in the project: 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 slurm-charms 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 the slurm charms as well as discuss potential -features and resolve personal support questions. It is expected that the users must remain respectful of -each other. Discussion moderators reserve the right to suspend discussions and/or delete posts that do not follow -this rule. +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: +### Monorepo + +* We use a mono repository (monorepo) for tracking the development of the Slurm charms. + All Slurm-related charms must be contributed to this repository and not + broken out into its own standalone repository. Here's why: + + * We can test against the latest commit to the Slurm charms rather than + pull what is currently published to edge on Charmhub. + * If the integration tests we're to pull the Slurm charms from the edge + branch on Charmhub, we can potentially waste CI minutes as we cannot + test breaking changes easily compared to just using the latest commit. + * It's easier to enable CI testing for development branches. We can test + the `experimental` development branch in the CI rather pipeline rather than need to create a separate workflow file off of `main`. + * We only need one branch protection to cover the Slurm charms. + * We only need one set of integration tests for all the Slurm charms + rather than multiple independent tests that repeat common operations. + * We only need one extensive set of documentation rather than individual + sets scoped per Slurm charm. + ### Juju & Operators * Adhere to the operator development best practices outlined in the [operator development styleguide](https://juju.is/docs/sdk/styleguide). @@ -194,10 +240,10 @@ The following guidelines must be adhered to if you are writing code to be merged * Adhere to the Python docstring conventions outlined in [Python Enhancement Proposal 257](https://www.python.org/dev/peps/pep-0257/). - * * Docstrings must follow the + * *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 slurm-charms, you agree to license your contribution under the +By contributing your code to the Slurm charms, you agree to license your contribution under the [Apache Software License, version 2.0](https://www.apache.org/licenses/LICENSE-2.0.html).