mirror of
https://github.com/Garmelon/PFERD.git
synced 2025-11-04 14:42:49 +01:00
85 lines
3.0 KiB
Markdown
85 lines
3.0 KiB
Markdown
# PFERD Development Guide
|
|
|
|
PFERD is packaged following the [Python Packaging User Guide][ppug] (in
|
|
particular [this][ppug-1] and [this][ppug-2] guide).
|
|
|
|
[ppug]: <https://packaging.python.org/> "Python Packaging User Guide"
|
|
[ppug-1]: <https://packaging.python.org/tutorials/packaging-projects/> "Packaging Python Projects"
|
|
[ppug-2]: <https://packaging.python.org/guides/distributing-packages-using-setuptools/> "Packaging and distributing projects"
|
|
|
|
## Setting up a dev environment
|
|
|
|
The use of [venv][venv] and [uv][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][venv-tut] and
|
|
[this section on "development mode"][ppug-dev].
|
|
|
|
[venv]: <https://docs.python.org/3/library/venv.html> "venv - Creation of virtual environments"
|
|
[venv-tut]: <https://docs.python.org/3/tutorial/venv.html> "12. Virtual Environments and Packages"
|
|
[uv]: <https://docs.astral.sh/uv/> "uv - An extremely fast Python package and project manager"
|
|
|
|
## 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
|
|
```
|