Skip to content

Latest commit

 

History

History
242 lines (176 loc) · 8.45 KB

CONTRIBUTING.md

File metadata and controls

242 lines (176 loc) · 8.45 KB

How To Contribute

Thank you for considering contributing to eurocropsml! Everyone is very welcome to help improve it.

This document is intended to help you get started and make the process of contributing more accessible. Do not be afraid ask if something is unclear!

Workflow

  • Every contribution is welcome, no matter how small! Do not hesitate to submit fixes for typos etc.
  • Try to stick to only one change or fix per merge/pull request.
  • Add tests and documentation for your code. Contributions missing tests or documentation can not be merged.
  • Make sure all changes pass our CI. We will usually not give any feedback until the CI is green unless you ask explicitly for it.
  • Once you have addressed review feedback bump the pull request with a short note, so we know you are done.

Branching Strategy

We use a simple feature branches approach.

  • Use a separate branch off main for each new feature/fix to be worked on
  • Use clear and consistent branch names, e.g., {#issue}-{feature-description}
  • Feature branches are merged into main using pull/merge requests
  • Whoever merges into main is responsible for adding appropriate notes to the CHANGELOG
  • We never directly push changes to main
  • Avoid branching off from another feature branch
%%{init: { 'theme': 'base', 'gitGraph': {'showCommitLabel': false}} }%%
gitGraph
  commit
  commit
  branch 42-some-feature
  checkout 42-some-feature
  commit
  commit
  checkout main
  merge 42-some-feature
  commit
  branch 43-another-feature
  checkout 43-another-feature
  commit
  commit
  commit
  checkout main
  merge 43-another-feature
  commit
Loading

Local Development Environment

You can (and should) run our test suite using tox. For a more traditional environment we recommend to develop using a Python 3.10 release.

Create a new virtual environment using your favorite environment manager. Then get an up to date checkout of the eurocropsml repository:

$ git clone https://github.com/dida-do/eurocropsml.git

Change into the newly created directory and activate your virtual environment if you have not done that already.

Makefile Installation and Testing (Recommended)

For convenience we have configured several commands that are frequently used during development into a Makefile.

You can install and editable version of the eurocropsml package with all its development dependencies:

$ make install

You can run our test suite against multiple Python versions:

$ make test

(Under the hood we use tox for this, see below.)

To avoid committing code not following our style guide, we advise you to always run our automated code formatting and linting after you have made changes:

$ make format lint

You can use

$ make help

to see a list of all available Makefile commands.

Manual Installation and Testing (Not Recommended)

Of course you can also run the installation, testing, formatting, and linting commands manually, e.g., in case you want control over extra command line options.

The alternative way to install an editable version of the eurocropsml package along with all its development dependencies is:

$ pip install -e '.[dev]'

Now you should be able to run tests against a single (currently active) Python version manually

$ python -m pytest

or use our configured tox environments, e.g.,

$ tox run -e py310,py311

to run tests against different Python versions 3.10 and 3.11.

(Similarly corresponding tox commands are also used by our Makefile under the hood.)

Code Style and Formatting

We generally follow PEP 8, PEP 257, and PEP 484 to the extent that it is checked/enforced by our configured black code formatter, flake8 linter, and mypy static type checker. We use isort to sort all imports.

The formatting can be automated. If you run our make or tox commands before committing (see above), you do not have to spend any thoughts or time on formatting your code at all.

Docstrings

  • We use google style docstrings and PEP 484 type hints for type annotations: 
    def function_with_type_annotations(param1: int, param2: str) -> bool:
    """Example function with type annotations.

    An optional more detailed description of the function behavior.

    Args:
        param1: The first parameter.
        param2: The second parameter.
    Returns:
        The return value. True for success, False otherwise.
    """
    ...
    class ExampleClass(object):
    """The summary line for a class docstring should fit on one line.

    If the class has public attributes, they may be documented here in an ``Attributes`` section and follow the same formatting as a function's ``Args`` section. 

    Attributes:
        attr1: Description of `attr1`.
        attr2: Description of `attr2`.

    Args:
        param1: Description of `param1`.
        param2: Description of `param2`.
            Multiple lines are supported as well.
        param3: Description of `param3`.

    """

    def __init__(self, param1: str, param2: int, param3: float):
        ...
  • If you make additions or changes to the public interface part of the package, tag the respective docstrings with .. versionadded:: XX.YY.ZZ <NOTE> or .. versionchanged:: XX.YY.ZZ <NOTE> directives.

Naming Conventions

We generally adhere to using

  • snake case lower_case_with_underscores for variables and functions
  • camel case CapitalizedWords for classes
  • capitalization UPPER_CASE_WITH_UNDERSCORES for constants and (global) configurations

Functions and methods should typically have names describing the effect/action that they perform, i.e. verbs as names, e.g., def parse_some_thing(...).

Classes and instances should typically have names describing the type of object, i.e. nouns as names, e.g., class SomeThingParser(...).

Tests

  • Write assertions as actual == expected for consistency: 
    x = f(...)

assert x.important_attribute == 42
assert x.another_attribute == "foobar"
  • Use our make or tox commands (see above) to run our tests. It will ensure the test suite runs with all the correct dependencies against all supported Python versions just as it will in our CI. If you lack Python versions, you can can limit the environments like tox -e py310,py311.
  • Write docstrings for your tests. Here are tips for writing good test docstrings.

Documentation

Governance

eurocropsml was created as part of a research project and is maintained by volunteers. We are always open to new members that want to help. Just let us know if you want to join the team.

Everyone is welcome to help review pull/merge requests of others but nobody should review and merge their own code.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. Please report any harm to the project team in any way you find appropriate.

Thank you again for considering contributing to eurocropsml!