Development¶
In case you want to participate in the development of pyorbs, you’re very welcome to do so! Here you can learn about some principles that we try to follow in order to make sure we produce software that doesn’t suck. It is assumed that you have a solid understanding of software development best practices and Python development in general.
General Principles¶
There are some software development concepts and ideas that are important when writing software that other people will rely on. In particular, you should always keep in mind the following principles:
No code shall be shipped without being thoroughly tested and reviewed first.
Write code that doesn’t smell.
Don’t repeat yourself. Just don’t.
Live the Zen of Python.
Coding Style¶
When writing code you should always follow the PEP8 Style Guide with the following exceptions:
Each line should be less than 100 characters long.
You should use Google-style docstrings starting on the second line.
Development Environment¶
You can manage the development environment of pyorbs with pyorbs itself. If you already have pyorbs
installed you can simply execute orb -m pyorbs
within the project folder, after which you can
execute orb pyorbs
and pip install -e .
to install the orb
command inside the
pyorbs
orb. This allows you to develop and test the orb
command itself while the pyorbs
orb is active.
Version Control¶
We use GitHub for version control and for aiding the review process. Before starting to work on a new feature, make sure that you are aligned with the maintainers to avoid developing things that may not get merged. Always work in separate feature branches and commit often. Once your changes are ready to be reviewed, create a pull request.
You should increment the version number according to the semantic versioning rules using bump2version. Make sure to document your changes in the Changelog as well.
Testing¶
The codebase is tested using the pytest framework. All
tests should reside in the tests
folder. The code must have complete test coverage through
meaningful unit and system tests. Make sure the tool is tested with all supported shells that are
listed in the Features section (for this you will need to install all of these shells
on your system).
You can run the test suite by simply executing pytest
.
Documentation¶
This documentation is created using Sphinx and can be
modified or expanded by changing the source files in the docs
folder. In order to re-build the
documentation just execute make
inside this folder while the pyorbs
orb is
active.
Continuous Deployment¶
You generally do not have to worry about this too much, as the continuous deployment system is
maintained by Webrepublic’s Data & Technology department. We use
Concourse for orchestrating the various tasks necessary for
publishing this package, including building and updating the documentation upon successful merging
into the master
branch.
In case hell breaks loose and you must publish pyorbs manually, do this:
$ ./setup.py sdist bdist_wheel
$ twine check dist/*
$ twine upload --repository-url https://test.pypi.org/legacy/ dist/*
$ twine upload dist/*
Do not forget to check your distribution on test.pypi.org before uploading it to PyPI.
Maintenance¶
This package is currently maintained by the Webrepublic Data & Technology department.