summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorBenjamin Drung <bdrung@debian.org>2023-06-10 08:55:33 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2023-06-10 09:21:49 +0000
commit88837172f69eabc408ae3945d82e0270b8e07440 (patch)
treed6b7fa06694f45d25f54f6ea9ded93c981e51f6f /CONTRIBUTING.md
parentInitial commit. (diff)
downloadnvme-stas-88837172f69eabc408ae3945d82e0270b8e07440.tar.xz
nvme-stas-88837172f69eabc408ae3945d82e0270b8e07440.zip
Adding upstream version 2.2.1.upstream/2.2.1
Signed-off-by: Benjamin Drung <bdrung@debian.org>
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md53
1 files changed, 53 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..11e30b7
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,53 @@
+# Contributing guidelines
+
+Thanks for contributing to this project. We'd like to get your feedback and suggestions.
+
+## Issues
+
+Bugs, feature requests, or issues must be reported through GitHub's "[Issues](https://github.com/linux-nvme/nvme-stas/issues)". Make sure there is not an existing open issue (or recently closed) for the same problem or feature. Include all pertinent info: environment, nvme-stas version, how to reproduce, expected result, etc.
+
+## Contribution process
+
+All contributions should be made through pull requests. Before submitting make sure that you followed the coding style (below) and you ran and passed the unit tests.
+
+### How to submit contributions
+
+1. Fork the repo
+2. Make changes. Try to split you changes into distinct commits and avoid making big reformatting as it makes it harder to review the changes.
+3. If possible, add unit tests for new features.
+4. Run `make black` to make sure the changes conform to coding styles. See [Coding styles]() below.
+5. Run `make test` and make sure all tests pass.
+6. Commit to your fork with descriptive message and use the "`--signoff, -s`" option
+7. Send the pull request
+8. Check for failures in the automated CI output.
+9. Be involved in the conversation (if any).
+
+## Coding style
+
+nvme-stas uses [black](https://black.readthedocs.io/en/stable/), [pylint](https://pylint.readthedocs.io/en/latest/), and [pyflakes](https://pypi.org/project/pyflakes/) to check that the code meets minimum style requirements. We use `black` with the following options.
+
+```bash
+black --diff --color --line-length 120 --skip-string-normalization [file or directory]
+```
+
+You can also use this convenience make command:
+
+```
+make black
+```
+
+## Minimum Python version required
+
+nvme-stas must be able to run with Python 3.6. Code changes cannot use Python features not supported by Python 3.6. The only exception is for Python scripts used during the build phase (e.g. scripts to generate the documentation) or test scripts. Those scripts can follow Python 3.8 syntax.
+
+nvme-stas uses [vermin](https://pypi.org/project/vermin/) to verify that the code submitted complies with the minimum version required. Vermin gets executed as part of the tests (see `make test` below).
+
+## Unit tests
+
+Unit tests can be run with this command:
+
+```bash
+make test
+```
+
+This command not only runs the unit tests, but also pylint, pyflakes, and vermin. Make sure that these programs are installed otherwise the tests will be skipped.