Skip to content

Commit 7f198ee

Browse files
MartinThomaMartinThoma
authored
DEV: Ensure consistent PR titles (#79)
1 parent 4d905e1 commit 7f198ee

File tree

7 files changed

+151
-4
lines changed

7 files changed

+151
-4
lines changed

‎.github/scripts/check_pr_title.py

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
"""Check that all PR titles follow the desired scheme."""
2+
3+
import os
4+
import sys
5+
6+
KNOWN_PREFIXES = (
7+
"SEC: ",
8+
"BUG: ",
9+
"ENH: ",
10+
"DEP: ",
11+
"PI: ",
12+
"ROB: ",
13+
"DOC: ",
14+
"TST: ",
15+
"DEV: ",
16+
"STY: ",
17+
"MAINT: ",
18+
"REL: ",
19+
)
20+
PR_TITLE = os.getenv("PR_TITLE", "")
21+
22+
if (
23+
not PR_TITLE.startswith(KNOWN_PREFIXES)
24+
or not PR_TITLE.split(": ", maxsplit=1)[1]
25+
):
26+
sys.stderr.write(
27+
f"The PR title '{PR_TITLE}' does not follow the projects naming scheme: "
28+
"https://pdfly.readthedocs.io/en/latest/dev/intro.html#commit-messages\n",
29+
)
30+
sys.stderr.write(
31+
"If you do not know which one to choose or if multiple apply, make a best guess. "
32+
"Nobody will complain if it does not quite fit :-)\n",
33+
)
34+
sys.exit(1)
35+
else:
36+
sys.stdout.write(f"PR title '{PR_TITLE}' appears to be valid.\n")

‎.github/workflows/title-check.yml

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: 'PR Title Check'
2+
on:
3+
pull_request:
4+
# check when PR
5+
# * is created,
6+
# * title is edited, and
7+
# * new commits are added (to ensure failing title blocks merging)
8+
types: [opened, reopened, edited, synchronize]
9+
10+
jobs:
11+
title-check:
12+
name: Title check
13+
runs-on: ubuntu-latest
14+
steps:
15+
- name: Checkout Code
16+
uses: actions/checkout@v4
17+
- name: Check PR title
18+
env:
19+
PR_TITLE: ${{ github.event.pull_request.title }}
20+
run: python .github/scripts/check_pr_title.py

‎Makefile

+1-1
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ upload:
1515
clean:
1616
python setup.py clean --all
1717
pyclean .
18-
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
18+
rm -rf tests/__pycache__ pdfly/__pycache__ Image9.png htmlcov docs/_build dist dont_commit_merged.pdf dont_commit_writer.pdf pdfly.egg-info
1919

2020
test:
2121
pytest tests --cov --cov-report term-missing -vv --cov-report html --durations=3 --timeout=30

‎docs/dev/intro.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Developer Intro
2+
3+
pdfly is an application and thus non-developers
4+
might also use it.
5+
6+
## Installing Requirements
7+
8+
```
9+
pip install -r requirements/dev.txt
10+
```
11+
12+
## Running Tests
13+
14+
See [testing pdfly with pytest](testing.md)
15+
16+
## Tools: git and pre-commit
17+
18+
Git is a command line application for version control. If you don't know it,
19+
you can [play ohmygit](https://ohmygit.org/) to learn it.
20+
21+
GitHub is the service where the pdfly project is hosted. While git is free and
22+
open source, GitHub is a paid service by Microsoft, but free in a lot of
23+
cases.
24+
25+
[pre-commit](https://pypi.org/project/pre-commit/) is a command line application
26+
that uses git hooks to automatically execute code. This allows you to avoid
27+
style issues and other code quality issues. After you entered `pre-commit install`
28+
once in your local copy of pdfly, it will automatically be executed when
29+
you `git commit`.
30+
31+
## Commit Messages
32+
33+
Having a clean commit message helps people to quickly understand what the commit
34+
is about, without actually looking at the changes. The first line of the
35+
commit message is used to [auto-generate the CHANGELOG](https://github.com/py-pdf/pdfly/blob/main/make_release.py).
36+
For this reason, the format should be:
37+
38+
```
39+
PREFIX: DESCRIPTION
40+
41+
BODY
42+
```
43+
44+
The `PREFIX` can be:
45+
46+
* `SEC`: Security improvements. Typically an infinite loop that was possible.
47+
* `BUG`: A bug was fixed. Likely there is one or multiple issues. Then write in
48+
the `BODY`: `Closes #123` where 123 is the issue number on GitHub.
49+
It would be absolutely amazing if you could write a regression test in those
50+
cases. That is a test that would fail without the fix.
51+
A bug is always an issue for pdfly users - test code or CI that was fixed is
52+
not considered a bug here.
53+
* `ENH`: A new feature! Describe in the body what it can be used for.
54+
* `DEP`: A deprecation. Either marking something as "this is going to be removed"
55+
or actually removing it.
56+
* `PI`: A performance improvement. This could also be a reduction in the
57+
file size of PDF files generated by pdfly.
58+
* `ROB`: A robustness change. Dealing better with broken PDF files.
59+
* `DOC`: A documentation change.
60+
* `TST`: Adding or adjusting tests.
61+
* `DEV`: Developer experience improvements, e.g. pre-commit or setting up CI.
62+
* `MAINT`: Quite a lot of different stuff. Performance improvements are for sure
63+
the most interesting changes in here. Refactorings as well.
64+
* `STY`: A style change. Something that makes pdfly code more consistent.
65+
Typically a small change. It could also be better error messages for
66+
end users.
67+
68+
The prefix is used to generate the CHANGELOG. Every PR must have exactly one -
69+
if you feel like several match, take the top one from this list that matches for
70+
your PR.
71+
72+
## Pull Request Size
73+
74+
Smaller Pull Requests (PRs) are preferred as it's typically easier to merge
75+
them. For example, if you have some typos, a few code-style changes, a new
76+
feature, and a bug-fix, that could be 3 or 4 PRs.
77+
78+
A PR must be complete. That means if you introduce a new feature it must be
79+
finished within the PR and have a test for that feature.

‎docs/dev/testing.md

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

‎docs/index.rst

+8-1
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,14 @@ pdfly is a command line tool to get informaiton about PDF documents and to manip
1919

2020

2121
.. toctree::
22-
:caption: About pypdf
22+
:caption: Developer Guide
23+
:maxdepth: 1
24+
25+
dev/intro
26+
dev/testing
27+
28+
.. toctree::
29+
:caption: About pdfly
2330
:maxdepth: 1
2431

2532
meta/CHANGELOG

‎docs/user/installation.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ There are several ways to install pdfly. The most common option is to use pip.
77
pdfly requires Python 3.6+ to run.
88

99
Typically Python comes with `pip`, a package installer. Using it you can
10-
install pypdf:
10+
install pdfly:
1111

1212
```bash
1313
pip install pdfly
1414
```
1515

1616
If you are not a super-user (a system administrator / root), you can also just
17-
install pypdf for your current user:
17+
install pdfly for your current user:
1818

1919
```bash
2020
pip install --user pdfly

0 commit comments

Comments
 (0)