pferd/DEV.md

PFERD Development Guide

PFERD is packaged following the Python Packaging User Guide (in particular this and this guide).

Setting up a dev environment

The use of venv is recommended. To initially set up a development environment, run these commands in the same directory as this file:

$ python -m venv .venv
$ . .venv/bin/activate
$ ./scripts/setup

The setup script installs a few required dependencies and tools. It also installs PFERD via pip install --editable ., which means that you can just run pferd as if it was installed normally. Since PFERD was installed with --editable, there is no need to re-run pip install when the source code is changed.

If you get any errors because pip can't update itself, try running ./scripts/setup --no-pip instead of ./scripts/setup.

For more details, see this part of the Python Tutorial and this section on "development mode".

Checking and formatting the code

To run a set of checks against the code, run ./scripts/check in the repo's root directory. This script will run a few tools installed by ./scripts/setup against the entire project.

To format the code, run ./scripts/format in the repo's root directory.

Before committing changes, please make sure the checks return no warnings and the code is formatted.

Contributing

When submitting a PR that adds, changes or modifies a feature, please ensure that the corresponding documentation is updated as well. Also, please ensure that ./scripts/check returns no warnings and the code has been run through ./scripts/format.

In your first PR, please add your name to the LICENSE file.

Releasing a new version

This section describes the steps required to release a new version of PFERD. Usually, they don't need to performed manually and scripts/bump-version can be used instead.

1. Update the version number in PFERD/version.py
2. Update CHANGELOG.md
3. Commit changes to master with message Bump version to <version> (e. g. Bump version to 3.2.5)
4. Create annotated tag named v<version> (e. g. v3.2.5)
   • Copy changes from changelog
   • Remove # symbols (which git would interpret as comments)
   • As the first line, add Version <version> - <date> (e. g. Version 3.2.5 - 2021-05-24)
   • Leave the second line empty
5. Fast-forward latest to master
6. Push master, latest and the new tag

Example tag annotation:

Version 3.2.5 - 2021-05-24

Added
- Support for concurrent downloads
- Support for proper config files
- This changelog

Changed
- Rewrote almost everything
- Redesigned CLI

Removed
- Backwards compatibility with 2.x