Skip to content

Latest commit

 

History

History
178 lines (145 loc) · 6.54 KB

CONTRIBUTING.md

File metadata and controls

178 lines (145 loc) · 6.54 KB
Raw

Contributing In General

You are very welcome to contribute to the open source repository of the IBM PAIRS Geoscope. To contribute code or documentation, please submit a pull request.

Setting up your development environment

You can start off a plan Python 2 or 3 setup. Right now the code is compatible with both, however, since the former fades out end of 2019, we focus on the latter.

To obtain all required Python module, simply run

pip install -r requirements.txt
pip install -r requirements-development.txt

from the base of this repo.

Proposing new features

If you would like to implement a new feature, please raise an issue before sending a pull request so the feature can be discussed. This is to avoid you wasting your valuable time working on a feature that the project developers are not interested in accepting into the code base.

Fixing bugs

If you would like to fix a bug, please raise an issue before sending a pull request so it can be tracked.

Merge approval

The project maintainers use LGTM (Looks Good To Me) in comments on the code review to indicate acceptance. A change requires LGTMs from one of the maintainers of each component affected.

For a list of the maintainers, see the MAINTAINERS.md page.

Legal

Each source file must include a license header for the BSD-Clause-3 Software License. Using the SPDX format is the simplest approach. e.g.

# Copyright <years> <holder> All Rights Reserved.
#
# SPDX-License-Identifier: BSD-3-Clause

We have tried to make it as easy as possible to make contributions. This applies to how we handle the legal aspects of contribution. We use the same approach - the Developer's Certificate of Origin 1.1 (DCO) - that the Linux® Kernel community uses to manage code contributions.

We simply ask that when submitting a patch for review, the developer must include a sign-off statement in the commit message.

Here is an example Signed-off-by line, which indicates that the submitter accepts the DCO linked above:

Signed-off-by: Your Name <your@mail.org>

You can include this automatically when you commit a change to your local git repository using the following command:

git commit -s

Alternatively/in addition you can have a template for your commit text in a file like git-commit-template with the DCO above. Then run git config commit.template git-commit-template to have it as your default when running git commmit ....

Testing

We ask and expect you to write test cases for the contribution you make, because it significantly helps to detect bugs while the project grows. Please place corresponding code into the tests directory. Please make pull requests after your contribution has passed all tests, only.

Please make sure

pytest

passes without error. Note, there is a set of environment variables such as PAW_TESTS_REAL_CONNECT, PAW_TESTS_PAIRS_PASSWORD_FILE_NAME, PAW_TESTS_PAIRS_USER, etc. which can be employed to configure the test suite at runtime.

Coding style guidelines

When writing code please adopt the following coding style guidelines:

  • Try to well document your code, ideally with an approximate ratio 1:3 of documentation to code.

  • Each function (of a class etc.) should have sufficient documentation on input, output, exceptions and how it processes information. The goal is to have all documentation required for the API in code such that Sphinx can automatically generate documentation. An example:

    def numbers_2_string(numbers):
    """
    This is a one-liner summarizing the function.

    And here comes more details.

    :param numbers:       list of random numbers to convert to string
    :type numbers:        [float]
    :returns:             the user given numbers, concatenated by space
    :rtype:               str
    :raises Exception:    if given input cannot be interpreted
                          if the input is not an iterable
    """
    # check that all elements in input are floating point numbers
    if not all(
      [
          isinstance(num, float)
          for num in numbers
      ]
    ):
        raise Exception("Sorry, input contains non-floating point elements.")

    # return space-concatenated numbers
    return ' '.join(numbers)

    note: This example also incorporates other aspects mentioned below

  • Try to reserve one line for each argument of a function/class (call), e.g. instead of

    funct(arg1, arg2, arg3=default1, argum4=default2, ...)

    this is preferred:

    funct(
  arg1,
  arg2,
  arg3    = default1,
  argum4  = default2,
  ...
)

    Similarely, it holds for dictionaries:

    {
  "key1": [
      {
          "subkey1": "val1",
          "subkey2": "val2",
          ...
      }
  ],
  "key2":  122.2,
  ...
}

    instead of

    {"key1":[{"subkey1":"val1","subkey2":"val2",...}],"key2":122.2,...}

  • For indentation, please use 4 simple space characters,

  • Try to avoid having more than 80 characters of code per line

  • it would be nice if you use (VIM-style) text folding markers ({{{ and }}}) to logically group your code.

  • Please choose descriptive names for variables, e.g. for quantities with physical units we tend to include the unit in the name, some examples:

    variable example description
    timeStartRunningSec simple variable using camel cases
    PingServer class instance having fist character upper case
    MAX_TIME_THESHOLD_MS a global constant with units miliseconds
    time_service_response a function name

    note: This way the code becomes more human readable (documentation of variable by name).

You can always take existing code as an example of good coding style.