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.

Issue Reporting

In case you encounter an issue feel free to let us know about it on GitHub.

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:

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:

  • Testing of GitHub pull requests after each new commit.

  • Package and documentation building and publication 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.