Environment and Utilities

The development environment is prepared and utilized via the develop.py program distributed with the project sources. This program is built against the Python standard library and has no third-party dependencies. It can locally bootstrap Python implementations and Python packages in a manner that does not intrude with either a system-wide or user-specific Python installation. Aside from a working Python of the minimum required version and a sane standard library distribution with that Python, there are no requirements which must be installed prior to development on the project.

There is a possible exception to the foregoing statement. If a Python implementation, which is specified for project development, requires compilation from sources, then you should ensure that appropriate C header files are installed for successful compilation of the interpreter and relevant standard library modules. The suggested build environment section of the Pyenv Wiki wiki has instructions for installing the relevant dependencies for various operating systems and package managers.

You can bootstrap the project development environment with the following command or similar, depending on your Python installation:

python3 develop.py bootstrap

While you can write python3 develop.py for each task invocation, there exists a shortcut for popular shells:

bash

eval "$(python3 develop.py ease --with-completions)"

By default, this will create a shell function, called devshim, which you can use as a command instead of python3 develop.py.

Commit Signatures

All commits to the project must be signed with a valid GPG/PGP or S/MIME secret key. You can use GNU Privacy Guard or a similar tool to generate a signing key if you do not already have one. And, you can likewise use such a tool to sign your commits. Github has a good guide on the following topics:

• Commit Signature Verification

• GPG Key Generation

• GPG Key Registration on Github

• Git Client Configuration for Commit Signatures

If you do not wish to expose a personal email address in association with a signing key, you can use the no-reply email address associated with your Github account instead.

In addition to registering the signature verification public key, which corresponds to your secret signing key, with Github, you may also publish the signature verification public key to well-known public key servers, such as:

• OpenPGP Keyserver

• Ubuntu Keyserver

EditorConfig

Most modern code editors support per-file type configuration via EditorConfig. This ensures that project standards for things, such as maximum line length, trailing whitespace, and indentation are enforced without the need for lots of editor-specific configurations to be distributed with the project. We recommend that you install an EditorConfig plugin for your editor of choice, if necessary. We provide an .editorconfig file at the top level of the project repository; this file has configurations relevant to the project.

pre-commit

As part of the development environment that we provide via Pipenv, there is the pre-commit command. Among other things, this allows you to install Git pre-commit hooks which will perform additional checks, such as TOML and YAML linting, before recording a new commit. These hooks will be installed if you ran python3 develop.py bootstrap. To update them at a later time you can run:

devshim freshen-git-hooks install-git-hooks