DEV: Ensure consistent PR titles (#79)

.github/scripts/check_pr_title.py

@@ -0,0 +1,36 @@
+"""Check that all PR titles follow the desired scheme."""
+
+import os
+import sys
+
+KNOWN_PREFIXES = (
+    "SEC: ",
+    "BUG: ",
+    "ENH: ",
+    "DEP: ",
+    "PI: ",
+    "ROB: ",
+    "DOC: ",
+    "TST: ",
+    "DEV: ",
+    "STY: ",
+    "MAINT: ",
+    "REL: ",
+)
+PR_TITLE = os.getenv("PR_TITLE", "")
+
+if (
+    not PR_TITLE.startswith(KNOWN_PREFIXES)
+    or not PR_TITLE.split(": ", maxsplit=1)[1]
+):
+    sys.stderr.write(
+        f"The PR title '{PR_TITLE}' does not follow the projects naming scheme: "
+        "https://pdfly.readthedocs.io/en/latest/dev/intro.html#commit-messages\n",
+    )
+    sys.stderr.write(
+        "If you do not know which one to choose or if multiple apply, make a best guess. "
+        "Nobody will complain if it does not quite fit :-)\n",
+    )
+    sys.exit(1)
+else:
+    sys.stdout.write(f"PR title '{PR_TITLE}' appears to be valid.\n")

.github/workflows/title-check.yml

@@ -0,0 +1,20 @@
+name: 'PR Title Check'
+on:
+  pull_request:
+    # check when PR
+    # * is created,
+    # * title is edited, and
+    # * new commits are added (to ensure failing title blocks merging)
+    types: [opened, reopened, edited, synchronize]
+
+jobs:
+  title-check:
+    name: Title check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+      - name: Check PR title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: python .github/scripts/check_pr_title.py

Makefile

@@ -15,7 +15,7 @@ upload:
 clean:
 	python setup.py clean --all
 	pyclean .
-	rm -rf tests/__pycache__ pypdf/__pycache__ Image9.png htmlcov docs/_build dist dont_commit_merged.pdf dont_commit_writer.pdf pypdf.egg-info pypdf_pdfLocation.txt
+	rm -rf tests/__pycache__ pdfly/__pycache__ Image9.png htmlcov docs/_build dist dont_commit_merged.pdf dont_commit_writer.pdf pdfly.egg-info
 
 test:
 	pytest tests --cov --cov-report term-missing -vv --cov-report html --durations=3 --timeout=30

docs/dev/intro.md

@@ -0,0 +1,79 @@
+# 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](testing.md)
+
+## Tools: git and pre-commit
+
+Git is a command line application for version control. If you don't know it,
+you can [play ohmygit](https://ohmygit.org/) 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](https://pypi.org/project/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](https://github.com/py-pdf/pdfly/blob/main/make_release.py).
+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.
+* `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 Request Size
+
+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.

docs/dev/testing.md

@@ -0,0 +1,5 @@
+# Testing
+
+pdfly uses [`pytest`](https://docs.pytest.org/en/latest/) for testing.
+
+To run the tests you need to install the CI (Continuous Integration) requirements by running `pip install -r requirements/ci.txt`.

docs/index.rst

@@ -19,7 +19,14 @@ pdfly is a command line tool to get informaiton about PDF documents and to manip
 
 
 .. toctree::
-   :caption: About pypdf
+   :caption: Developer Guide
+   :maxdepth: 1
+
+   dev/intro
+   dev/testing
+
+.. toctree::
+   :caption: About pdfly
    :maxdepth: 1
 
    meta/CHANGELOG

docs/user/installation.md

@@ -7,14 +7,14 @@ There are several ways to install pdfly. The most common option is to use pip.
 pdfly requires Python 3.6+ to run.
 
 Typically Python comes with `pip`, a package installer. Using it you can
-install pypdf:
+install pdfly:
 
 ```bash
 pip install pdfly
 ```
 
 If you are not a super-user (a system administrator / root), you can also just
-install pypdf for your current user:
+install pdfly for your current user:
 
 ```bash
 pip install --user pdfly