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 and uv is recommended. To initially set up a development environment, run these commands in the same directory as this file:

$ uv sync
$ . .venv/bin/activate

This install all required dependencies and tools. It also installs PFERD as 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 uv sync when the source code is changed.

For more details, see this part of the Python Tutorial and [this section on "development mode"][ppug-dev].

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