Contributing¶
pyLXD development is done on Github. Pull Requests and Issues should be filed there. We try and respond to PRs and Issues within a few days.
If you would like to contribute major features or have big ideas, it’s best to
post at the Linux Containers disucssion forum to discuss your ideas before
submitting PRs. If you use [pylxd]
in the title, it’ll make it clearer.
Adding a Feature or Fixing a Bug¶
The main steps are:
There needs to be a bug filed on the Github repository. This is also for a feature, so it’s clear what is being proposed prior to somebody starting work on it.
The pyLXD repository must be forked on Github to the developer’s own account.
The developer should create a personal branch, with either:
- feature/name-of-feature
- bug/number/descriptive-name-of-bug
This can be done with
git checkout -b feature/name-of-feature
from the master branch.Work on that branch, push to the personal GitHub repository and then create a Pull Request. It’s a good idea to create the Pull Request early, particularly for features, so that it can be discussed and help sought (if needed).
When the Pull Request is ready it will then be merged.
At regular intervals the pyLXD module will be released to PyPi with the new features and bug fixes.
Requirements to merge a Pull Request (PR)¶
In order for a Pull Request to be merged the following criteria needs to be met:
- All of the commits in the PR need to be signed off using the ‘-s’ option with git commit. This is a requirement for all projects in the Github Linux Containers projects space.
- Unit tests are required for the changes. These are in the
pylxd/tests
directory and follow the same directory structure as the module. - The unit test code coverage for the project shouldn’t drop. This means that
any lines that aren’t testable (for good reasons) need to be explicitly
excluded from the coverage using
# NOQA
comments. - If the feature/bug fix requires integration test changes, then they should
be added to the
integration
directory. - If the feature/bug fix changes the API then the documentation in the
doc/source
directory should also be updated. - If the contributor is new to the project, then they should add their
name/details to the
CONTRIBUTORS.rst
file in the root of the repository as part of the PR.
Once these requirements are met, the change will be merged to the repository. At this point, the contributor should then delete their private branch.
Code standards¶
pyLXD follows PEP 8 as closely as practical. To check your compliance, use the pep8 tox target:
tox -e pep8
Note
if this fails then the code will not be merged. If there is a good
reason for a PEP8 non-conformance, then a # NOQA
comment should be
added to the relevant line(s).
Testing¶
Testing pyLXD is in 3 parts:
- Conformance with PEP 8, using the
tox -e pep8
command. - Unit tests using
tox -e py27
andtox -e py3
. - Integration tests using the
run_integration_tests
script in the root of the repository.
Note
all of the tests can be run by just using the tox
command on it’s
own, with the exception of the integration tests. These are not
automatically run as they require a working LXD environment.
All of the commands use the Tox automation project to run tests in a sandboxed environment. On Ubuntu this is installed using:
sudo apt install python-tox
Unit Testing¶
pyLXD tries to follow best practices when it comes to testing. PRs are gated by Travis CI and CodeCov. It’s best to submit tests with new changes, as your patch is unlikely to be accepted without them.
To run the tests, you should use Tox:
tox
Integration Testing¶
Integration testing requires a running LXD system. At present this is not performed by the CI system, although this is intended at some point in the future. Integration testing should be performed prior to merging a PR.
Currently, there are two variants of the script to run integration tests:
run_integration_tests-16-04
run_integration_tests-18-04
The default is run_integration_tests-18-04
, which is symlinked to
run_integration_tests
. This is because the default is to test on Ubuntu
Bionic, with Ubuntu Xenial (16.04) for maintenance purposes.
Note
A script to automate running the integration tests needs to be added.
Some hints on how to run the integration tests:
- On Ubuntu it’s probably easiest to use the Multipass snap.
- Launch an LTS instance using
multipass launch -n foo
- Shell into the instance:
multipass exec foo -- bash
- Install tox and python2.7:
sudo apt install python-tox python-2.7
- Clone the branch from the PR (or otherwise copy the repo into the machine)
- Configure LXD using
lxd init
– follow the prompts provided. - Run the integration tests.