Contributing

Wildland is an Open Source project, therefore community contribution plays a key role in its life cycle. If you wish to contribute, please see all of the requirements listed below.

Ways to contribute

Want to contribute to Wildland? That is great! There are a few ways you can contribute:

  1. Test Wildland and share any bugs, thoughts, new use cases and ideas with us by creating a new issue on Wildland GitLab.

  2. Pick any unassigned issue from Wildland Gitlab and try to resolve it.

  3. Implement a plugin for a new type of storage.

  4. Expand or improve Wildland documentation.

  5. Start building your Wildland forest and share it with your friends.

To add any code or documentation to the Wildland repository, you need to fork the project, create a feature branch, do some work on it and run all available tests. If all of the tests pass successfully, you can open a new merge request that will be reviewed by Wildland’s core development team. You can expect that you will need to iteratively address all of the code review comments you will get. When there will be no more review comments, your branch will be merged into the master. In this very moment you will officially become Wildland’s contributor.

Coding Style Guide

As a rule of thumb: look around and stick to the coding conventions that dominate the code. Wildland is mostly written in Python 3 with some tests and scripts written in Bash.

Python

For Python code, follow PEP-8 style guide. There may be exceptions to the rules imposed by PEP-8, which are defined in .pylintrc configuration file. One notable example is the limit to 100 characters for all lines instead of the maximum of 79 and 72 characters for code and comments, respectively. Also if you create a new file you should add a copyright notice at the top (the template can be found in the copyright_template file). If for some reason you think this file should not contain a copyright notice you can choose from multiple pylint’s disable keywords and place it at the top like:

# pylint: disable=copyright-violation,copyright-formatting,copyright-author-formatting

To ensure you are following the coding conventions, run pylint linter with the .pylintrc configuration file you can find in the Wildland repository. To make sure your code is accepted by the GitLab CI/CD pipeline, run:

cd docker
docker-compose build
docker-compose run wildland-client-ci ./ci/ci-lint

If after running the above commands you see:

Your code has been rated at 10.00/10

you are ready to open a merge request.

Bash

We don’t use any linters for Bash, but in the future we may want to use shellcheck so you can stick to their rules. Alternatively, follow the Google Shell Style Guide.

Documentation

Wildland documentation consists of:

  1. Python Documentation Strings (a.k.a. docstrings) described in PEP-257,

  2. Manual pages (a.k.a. manpages) formatted with reStructuredText saved in Documentation/*.rst files.

To convert *.rst documentation into HTML, PDF or any other format supported by Sphinx, run:

cd docker
docker-compose build
docker-compose run wildland-client-ci ./ci/ci-docs

Alternatively you can generate docs without using Docker:

make env
. ./env/bin/activate
cd Documentation/
make html

You should add docstrings to all of the public methods, classes and modules.

Commit messages

Keep your git history clean before opening merge request. When you commit your code, follow good practices, in particular: - explain the reason for the change, - refer to related GitLab tickets (e.g. fixes #100), - make it searchable: if your commit fixes a bug, you can mention error message that inspired the change, - don’t just explain _what_ you’ve changed, but also _why_.

License, Contributor Agreement

The Wildland Client code is licensed under GPLv3 license.

In order to be able to contribute to any Wildland repository, you will need to agree to the terms of the Wildland Contributor Agreement. By contributing to any such repository, you agree that your contributions will be licensed under the GPLv3 License.