Skip to content

Latest commit

 

History

History
194 lines (135 loc) · 6.21 KB

contribution_guide.rst

File metadata and controls

194 lines (135 loc) · 6.21 KB
Raw

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.

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.

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.