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:
Test Wildland and share any bugs, thoughts, new use cases and ideas with us by creating a new issue on Wildland GitLab.
Pick any unassigned issue from Wildland Gitlab and try to resolve it.
Implement a plugin for a new type of storage.
Expand or improve Wildland documentation.
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.
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.
Wildland documentation consists of:
Manual pages (a.k.a. manpages) formatted with reStructuredText saved in
*.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.
python3 -m http.server 8001 --directory _build/html
go to http://0.0.0.0:8001/
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.