Skip to content

Commit

Permalink
docs: update contributing guidelines
Browse files Browse the repository at this point in the history 
- 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 <[email protected]>
  • Loading branch information
@NucciTheBoss @jedel1043
NucciTheBoss authored and jedel1043 committed Aug 9, 2024
1 parent ec25612 commit a917458
Showing 1 changed file with 105 additions and 59 deletions.
164 changes: 105 additions & 59 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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

Expand All @@ -68,60 +73,73 @@ 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__ &mdash; ensure that your issue is not being caused by either a semantic or syntactic
error in your testlet's code.
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.
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 commit to
the `main` branch in the repository.
3. __Check if the issue has already been fixed__ &mdash; try to reproduce your issue
using the latest version of the Slurm charms.

4. __Isolate the problem__ &mdash; the more pinpointed the issue is, the easier time the developers will have fixing it.
4. __Isolate the problem__ &mdash; 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 &mdash; patches, improvements, new features &mdash; are a huge help. These pull requests should
remain focused in scope and should not contain unrelated commits.
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 (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:

```bash
# Clone your fork of the repo into the current directory
git clone https://github.com/<your-username>/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
```
Expand All @@ -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:
Expand All @@ -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).
Expand All @@ -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).

0 comments on commit a917458

Please sign in to comment.