Contribution Guide
What should I do before I get started?
You need to go through few steps to get the ball rolling. But no worries, it is pretty straightforward.
Accounts
First of all, you need accounts for:
Github account, some of you might already have one. If not, you can go to github and register a free user account in 2 minutes.
Note
If you are working for a company and the work you are going to contribute is in the name of the company, please register your account using company email address.
Eclipse account, since Kiso-testing is an Eclipse project
(full name: Eclipse Kiso-testing), you need an Eclipse account. Go to https://accounts.eclipse.org/user/register to register one for free.
After a successful registration, you need to hook up your github account with Eclipse account. Login in Eclipse foundation website and go to ‘Edit My Profile’ where you can bind your github account information.
ECA signing
ECA stands for ‘Eclipse Contributor Agreement’, which is a prerequisite to become a contributor. No paper work needed, go to https://www.eclipse.org/legal/ECA.php , read it carefully and follow its instruction to sign.
DCO signing
DCO stand for “Developer’s Certificate of Origin”, which you will encounter as part of ECA signing process. It is highly recommended that you read it, while you as a developer might overlook the legal consequences if the way you contribute does not follow certain rules and regulations.
License
License is one of the few first things people would think of, when they use or develop an open source project. Eclipse Kiso is and will be developed under the EPL v2.0 license from Eclipse foundation. Of course this exclude 3rd party source code.
EPL v2.0 is available under https://www.eclipse.org/legal/epl-2.0/ . You need read it carefully before using Kiso-testing or developing on Kiso-testing and make sure that you understand your rights and obligations.
Any contributions to Kiso-testing project code base needs to be licensed under EPL v2.0.
How to setup my environment?
Requirements
Python 3.7+
poetry (used to get the rest of the requirements)
Install
git clone https://github.com/eclipse/kiso-testing.git
cd kiso-testing
poetry install
poetry shell
Pre-Commit
To improve code-quality, a configuration of pre-commit hooks are available. The following pre-commit hooks are used:
black
flake8
isort
trailing-whitespace
end-of-file-fixer
check-docstring-first
check-json
check-added-large-files
check-yaml
debug-statements
If you don’t have pre-commit installed, you can get it using pip:
pip install pre-commit
Start using the hooks with
pre-commit install
Demo using example config
invoke run
Running the Tests
invoke test
or
pytest
Building the Docs
invoke docs
What should I do before committing ?
PEP8-Compliancy
In order to maintain clear and user-friendly project, make sure that your changes respect PEP8 standards. PEP8 is a guide that provides Python coding conventions (naming, indentation,…). Official document : https://peps.python.org/pep-0008/
To make sure your changes are PEP8 Compliant, different tools exist to help you here:
- linter (applicable on IDE) :
show some warning directly on IDE.
- pre-commit hook :
hook scripts that lint the added code using flake8 and format it using black and isort.
Typography
Most of the comments made during PR-Reviewing are about typography/misspelling mistakes. An easy way to avoid these is by running codespell on your written code.
Function type hinting
In kiso-testing, every implemented function must have annotations for its parameters and return types (type hints). This results in increased readability and therefore in easier comprehension of the code for any reader.
def some_fun(some_dict_param: dict, some_string_param: str) -> list:Note
As not every types are available in the builtins, or as it is important to precise inner type you might import some from collections module or typing
from typing import List from collections import namedtuple def some_fun( some_int_list_param: List[int], some_imported_type_param: namedtuple ) -> list:
Unit Testing
To ensure the correct behaviour of your code, add unit tests for every function you implemented.A convenient and pythonic way to do this is this is given by pytest Code coverage is measured with codecov. It simply checks if the code coverage is not going lower than it was before changes.
Examples Adaptation
To ensure proper integration of your changes into the existing features, and demonstrate their usages, adapt the examples of modified module, and run it locally.
Update Documentation
Regarding documentation there are four main purposes that have to be fulfilled before committing :
- Documentation regarding the changes :
Make sure that the documentation allow easy understanding of the new feature(s).This step mainly concern docstring (module, class, and function) as shown below, but you could also have to change .rst documentation if your changes concern general working principle of the ITF (e.g. cli) To ensure proper formatting of the documentation, run
invoke docs
in the poetry environment.""" name_of_the_module ****************** :module: name_of_the_module :synopsis: short description of the module. Extended description of the module's functionnality, how it works, etc .. currentmodule:: name_of_the_module """class ClassName: """Short description of class"""def fun(param1, param2): """Short description of fun. More extended description of the function if needed. :param param1: short description of param1 :param param2: short description of param2 :raise exception1: short description of raised exception :return: short description of the return parameter """Note
Make also sure to do the type hinting for exceptions
- What’s new section:
Add your changes into the what’s new section, so user can stay updated of the brand new features.
- Changelog: (automatically updated)
Your commit needs to follow the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) pattern. Changelog is updated automatically with the commit message.
Documentation has to build properly.