Developer Intro

pdfly is an application and thus non-developers might also use it.

Installing Requirements

pip install -r requirements/dev.txt

Running Tests

See testing pdfly with pytest

Documentation

To preview the HTML documentation, you can run this command:

sphinx-autobuild docs docs/_build/html

Tools: git and pre-commit

Git is a command line application for version control. If you don’t know it, you can play ohmygit to learn it.

GitHub is the service where the pdfly project is hosted. While git is free and open source, GitHub is a paid service by Microsoft, but free in a lot of cases.

pre-commit is a command line application that uses git hooks to automatically execute code. This allows you to avoid style issues and other code quality issues. After you entered pre-commit install once in your local copy of pdfly, it will automatically be executed when you git commit.

Commit Messages

Having a clean commit message helps people to quickly understand what the commit is about, without actually looking at the changes. The first line of the commit message is used to auto-generate the CHANGELOG. For this reason, the format should be:

PREFIX: DESCRIPTION

BODY

The PREFIX can be:

  • SEC: Security improvements. Typically an infinite loop that was possible.

  • BUG: A bug was fixed. Likely there is one or multiple issues. Then write in the BODY: Closes #123 where 123 is the issue number on GitHub. It would be absolutely amazing if you could write a regression test in those cases. That is a test that would fail without the fix. A bug is always an issue for pdfly users - test code or CI that was fixed is not considered a bug here.

  • ENH: A new feature! Describe in the body what it can be used for.

  • DEP: A deprecation. Either marking something as “this is going to be removed” or actually removing it.

  • PI: A performance improvement. This could also be a reduction in the file size of PDF files generated by pdfly.

  • ROB: A robustness change. Dealing better with broken PDF files.

  • DOC: A documentation change. Docs: is also allowed for commits made by DependaBot.

  • TST: Adding or adjusting tests.

  • DEV: Developer experience improvements, e.g. pre-commit or setting up CI.

  • MAINT: Quite a lot of different stuff. Performance improvements are for sure the most interesting changes in here. Refactorings as well.

  • STY: A style change. Something that makes pdfly code more consistent. Typically a small change. It could also be better error messages for end users.

The prefix is used to generate the CHANGELOG. Every PR must have exactly one - if you feel like several match, take the top one from this list that matches for your PR.

Pull Requests

Smaller Pull Requests (PRs) are preferred as it’s typically easier to merge them. For example, if you have some typos, a few code-style changes, a new feature, and a bug-fix, that could be 3 or 4 PRs.

A PR must be complete. That means if you introduce a new feature it must be finished within the PR and have a test for that feature.

Releases

To perform a new release, there is the checklist to follow:

  1. update __version__ in pdfly/_version.py & CHANGELOG.md in order to specify the release date for the new version

  2. perform a REL-prefixed commit, e.g; REL: X.Y.0", then make & merge a PR for it. The Github Actions pipeline should create a new git tag, and then publish a new version on Pypi: https://pypi.org/project/pdfly/#history

  3. edit the GitHub release note, using the CHANGELOG.md content for the description