From 7ebd950f98c869842bc4bb3c1a1fd1030b387179 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Rozet?= Date: Tue, 28 Mar 2023 16:37:08 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=B8=20Add=20contributing=20guidelines?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/ISSUE_TEMPLATE/documentation.md | 2 +- CONTRIBUTING.md | 54 +++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md index 3ca8a7c..511ca5d 100644 --- a/.github/ISSUE_TEMPLATE/documentation.md +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -7,7 +7,7 @@ labels: documentation ### Description -A clear description of what the issue is and where it is in the documentation (e.g [ssim.html#piqa.ssim.ssim](https://francois-rozet.github.io/piqa/ssim.html#piqa.ssim.ssim)). +A clear description of what the issue is and where it is in the documentation. ### Expectation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..de66a05 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,54 @@ +# Contributing guidelines + +First off, thank you for taking the time to contribute! 🎉 + +This document is a set of guidelines for contributing to the `piqa` package, which includes how to ask questions, report issues, suggest enhancements, contribute code, etc. + +## I just have a question + +Please **don't file an issue** to ask a question. We use [GitHub discussions](https://github.com/francois-rozet/piqa/discussions) as community forum for people to ask questions, share ideas or seek help. Before submitting your question, check whether it is addressed by the [documentation](https://piqa.readthedocs.io) or has already been asked in the discussions. If it has but the answer does not satisfy you, add a comment to the existing discussion instead of opening a new one. + +## Submit an issue + +Bugs and enhancements are tracked as [GitHub issues](https://github.com/francois-rozet/piqa/issues). For common issues, such as bug reports and feature requests, templates are provided. It is strongly recommended to use them as it helps understand and resolve issues faster. A clear and concise title (e.g. "RuntimeError with X when Y") also helps other users and developers to find relevant issues. + +Before submitting any issue, please perform a thorough search to see if your problem or a similar one has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. If you only find closed issues related to your problem, open a new one and include links to the closed issues in the description. + +## Contribute code + +If you like the project and wish to contribute, you can start by looking at issues labeled `good first issue` (should only require a few lines of code) or `help wanted` (more involved). If you found a bug and want to fix it, please create an issue reporting the bug before creating a pull request. Similarly, if you want to add a new feature, first create a feature request issue. This allows to separate the discussions related to the bug/feature, from the discussions related to the fix/implementation. + +### Code conventions + +We mostly follow the [PEP 8](https://peps.python.org/pep-0008/) style guide for Python code. It is recommended that you format your code with the opinionated [Black](https://github.com/psf/black) formatter. For example, if you created or modified a file `path/to/filename.py`, you can reformat it with + +``` +black -S path/to/filename.py +``` + +Additionally, please follow these rules: + +* Use single quotes for strings (`'single-quoted'`) but double quotes (`"double-quoted"`) for text such as error messages. +* Use informative but concise variable names. Single-letter names are fine if the context is clear. +* Avoid explaining code with comments. If something is hard to understand, simplify or decompose it. +* If Black's output [takes too much vertical space](https://github.com/psf/black/issues/1811), ignore its modifications. + +### Documentation + +The package's [documentation](https://piqa.readthedocs.io) is automatically built by [Sphinx](https://www.sphinx-doc.org) using type hints and docstrings. All classes and functions accessible to the user should be documented with [Google style](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) docstrings. All docstrings should have a basic "Example" section, which will be tested as part of our test suite. You can build the documentation locally with + +``` +cd docs +pip install -r requirements.txt +sphinx-build . html +``` + +### Commits + +There are no rules for commits and commit messages, but we recommend to + +* Avoid uninformative commit messages (e.g. "fix bug", "update", "typo"). +* Use the present tense and imperative mood ("Add X" instead of "Added X" or "Adds X"). +* Avoid small commits that revert/fix something introduced in the previous ones. Remember `git commit --amend` is your best friend. +* Consider [starting commit messages with an emoji](https://gitmoji.dev) to illustrate the intent of commits. +* Have fun!