Skip to content

Latest commit

 

History

History
54 lines (34 loc) · 3.92 KB

CONTRIBUTING.md

File metadata and controls

54 lines (34 loc) · 3.92 KB
Raw

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 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 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. 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 style guide for Python code. It is recommended that you format your code with the opinionated 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, ignore its modifications.

Documentation

The package's documentation is automatically built by Sphinx using type hints and docstrings. All classes and functions accessible to the user should be documented with Google style 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 to illustrate the intent of commits.
  • Have fun!