118 lines
4 KiB
Markdown
118 lines
4 KiB
Markdown
# Contributing to `flatbids`
|
|
|
|
- [Developer cheat sheet](#developer-cheat-sheet)
|
|
- [Code organization](#code-organization)
|
|
- [Style guide](#contribution-style-guide)
|
|
|
|
|
|
## Developer cheat sheet
|
|
|
|
[Hatch](https://hatch.pypa.io) is used as a convenience solution for packaging and development tasks.
|
|
Hatch takes care of managing dependencies and environments, including the Python interpreter itself.
|
|
If not installed yet, installing via [uv](https://docs.astral.sh/uv) is recommended (`uv tool install hatch`).
|
|
|
|
Below is a list of some provided convenience commands.
|
|
An accurate overview of provided convenience scripts can be obtained by running: `hatch env show`.
|
|
All command setup can be found in `pyproject.toml`, and given alternatively managed dependencies, all commands can also be used without `hatch`.
|
|
|
|
### Run the tests (with coverage reporting)
|
|
|
|
```
|
|
hatch test [--cover] [--all]
|
|
```
|
|
|
|
This can also be used to run tests for a specific Python version only:
|
|
|
|
```
|
|
hatch test -i py=3.10 [<select tests>]
|
|
```
|
|
|
|
### Build the HTML documentation (under `docs/_build/html`)
|
|
|
|
```
|
|
hatch run docs:build
|
|
# clean with
|
|
hatch run docs:clean
|
|
```
|
|
|
|
### Check type annotations
|
|
|
|
```
|
|
hatch run types:check
|
|
```
|
|
|
|
### Check commit messages for compliance with [Conventional Commits](https://www.conventionalcommits.org)
|
|
|
|
```
|
|
hatch run cz:check-commits
|
|
```
|
|
|
|
### Show would-be auto-generated changelog for the next release
|
|
|
|
```
|
|
hatch run cz:show-changelog
|
|
```
|
|
|
|
### Create a new release
|
|
|
|
```
|
|
hatch run cz:bump-version
|
|
```
|
|
|
|
The new version is determined automatically from the nature of the (conventional) commits made since the last release.
|
|
A changelog is generated and committed.
|
|
|
|
In cases where the generated changelog needs to be edited afterwards (typos, unnecessary complexity, etc.), the created version tag needs to be advanced.
|
|
|
|
|
|
### Build a new source package and wheel
|
|
|
|
```
|
|
hatch build
|
|
```
|
|
|
|
### Publish a new release to PyPi
|
|
|
|
```
|
|
hatch publish
|
|
```
|
|
|
|
## Contribution style guide
|
|
|
|
A contribution must be complete with code, tests, and documentation.
|
|
|
|
### Documentation
|
|
|
|
Docstrings should be complete with information on parameters, return values, and exception behavior. Documentation should be added to and rendered with the sphinx-based documentation.
|
|
|
|
### Commits
|
|
|
|
Commits and commit messages must be [Conventional Commits](https://www.conventionalcommits.org). Their compliance is checked for each pull request. The following commit types are recognized:
|
|
|
|
- `feat`: introduces a new feature
|
|
- `fix`: address a problem, fix a bug
|
|
- `doc`: update the documentation
|
|
- `rf`: refactor code with no change of functionality
|
|
- `perf`: enhance performance of existing functionality
|
|
- `test`: add/update/modify test implementations
|
|
- `ci`: change CI setup
|
|
- `style`: beautification
|
|
- `chore`: results of routine tasks, such as changelog updates
|
|
- `revert`: revert a previous change
|
|
- `bump`: version update
|
|
|
|
Any breaking change must have at least one line of the format
|
|
|
|
BREAKING CHANGE: <summary of the breakage>
|
|
|
|
in the body of the commit message that introduces the breakage. Breaking changes can be introduced in any type of commit. Any number of breaking changes can be described in a commit message (one per line). Breaking changes trigger a major version update, and form a dedicated section in the changelog.
|
|
|
|
### Pull requests
|
|
|
|
Contributions submitted via a pull-request (PR), are expected to be a clear, self-describing series of commits. The PR description is largely irrelevant, and could be used for a TODO list, or conversational content. All essential information concerning the code and changes **must** be contained in the commit messages.
|
|
|
|
Commit series should be "linear", with individual commits being self-contained, well-described changes.
|
|
|
|
If possible, only loosely related changes should be submitted in separate PRs to simplify reviewing and shorten time-to-merge.
|
|
|
|
Long-standing, inactive PRs (draft mode or not) are frowned upon, as they drain attention. It is often better to close a PR and open a new one, once work resumes. Maintainers may close inactive PRs for this reason at any time.
|