We are really happy to know that you want to contribute to the project! However, to ensure that the project keeps improving without compromising its integrity or quality, please follow this guide to ensure that your contribution is as useful as possible.
- What to know before contributing
- How can I contribute?
- Styleguides
- Issues, Commits and Pull Requests
This project is still at a proof of concept stage. That means the final repository organization and/or name might change. And please read also our:
Before creating bug reports, please check if the problem 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 find a Closed issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
If the problem hasn't been reported, create a new GitHub issue, providing the following information:
- A clear and descriptive title for the issue to identify the problem.
- A description of the steps which reproduce the problem, as detailed as possible.
- Describe the behavior you observed after following the steps and why that behaviour is erroneous or unexpected.
- If possible, include screenshots and animated GIFs
Features / improvement suggestions are submitted as GitHub issues. Please, before submitting a new one, please check if the improvement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. When creating an improvement issue, please provide the following information:
- Use a clear and descriptive title for the issue to identify the suggestion.
- Provide a description of the suggested enhancement as detailed as possible
- Explain why this improvement would be useful to most users
Before writing any code for the repository please do the following:
- Review the applicable styleguides.
- Check that the new code will not compromise the quality, stability or security of the codebase.
- Any new code is added to the repository using Pull Requests that must be reviewed and approved by the community before being merged or rebased to the repository.
- When creating the commit and the pull request, please refer also to the section Issues, Commits and Pull Requests.
- Whenever it is possible, new features should have Unit Tests to maintain (or increase) the code test coverage before adding it.
New documentation contributions are also welcomed. They can improve the official documentation, add new examples or tutorials. The new documents must be added to the "documentation" folder, and they must be created or modified using the same issue - pull request method as the code contributions. Document format should be Markdown unless an alternative format is really necessary. Naming should adhere to underscore kebab-case.
-
Clarity at the point of use is your most important goal. Clarity is more important than brevity
-
Projects should not throw any warnings when built.
We are using autopep8 to enforce PEP 8 -- Style Guide for Python
-
Include all the words needed to avoid ambiguity, but omit needless words
-
Name entities according to their roles, rather than their type constraints.
-
Names of types and protocols are UpperCamelCase. Everything else is lowerCamelCase.
-
Declarations should form correct human-readable phrases when read aloud.
-
Methods without side-effects have noun names (originalSize()). Methods with side effects have imperative verb names (sort()). Non-mutating methods that return new values have past participle names (sorted()) or a noun if the operation is naturally described by it (union())
-
Protocols that describe what something is should read as nouns (Collection). Protocols that describe a capability should be named using -able, -ible, or -ing (Equatable, ProgressReporting).
-
Avoid abbreviations
-
Self-documented code is preferred over comments.
-
When completely needed, comments must be written using double slash (//) instead of block syntax (/.../). Comments must be kept up-to-date or deleted.
-
Public APIs should have HeaderDoc documentation using JavaDoc standards.
-
All imports go alphabetically sorted at the very beginning of the file. Empty lines between imports are not used.
-
Import only the modules a source file requires.
-
Do not insert a blank line between imports.
Documentation should use Markdown (.md) format. It must be written at least in English, but additional localized versions are also possible.
Each pull request for new commits must be related to a particular issue, and will be reviewed by the community before being merged or rebased to the codebase.
Every issue should have its branch following this format: "issue-##-short-description-using-kebab-case"
-
Use the present tense and imperative mood ("Add feature", "Change cursor color")
-
Limit the first line to 72 characters or less
-
Reference issues and pull requests liberally after the first line
-
Consider starting the commit message with an applicable emoji (taken from the Atom Contribution Guidelines):
- 🎨
:art:when improving the format/structure of the code - 🐎
:racehorse:when improving performance - 🚱
:non-potable_water:when plugging memory leaks - 📝
:memo:when writing docs - 🐛
:bug:when fixing a bug - 🔥
:fire:when removing code or files - ✅
:white_check_mark:when adding tests - 🔒
:lock:when dealing with security - 👕
:shirt:when removing linter warnings
- 🎨