pferd/DEV.md
2021-05-24 20:23:14 +02:00

3.3 KiB

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