Skip to content

Commit 7802aaf

Browse files
joshuadavidthomasjoshuadavidthomas
authored
add Development section to README and update contribution guide (#12)
* add Development section to README and update contribution guide * tweaks * adjust just commands * adjustments * adjust * add section on coverage * add linting * tweak * last tweak
1 parent b1c1af1 commit 7802aaf

File tree

3 files changed

+149
-29
lines changed

3 files changed

+149
-29
lines changed

‎CONTRIBUTING.md

Lines changed: 138 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,58 +2,168 @@
22

33
All contributions are welcome! Besides code contributions, this includes things like documentation improvements, bug reports, and feature requests.
44

5-
You should first check if there is a [GitHub issue](https://github.com/joshuadavidthomas/django-bird/issues) already open or related to what you would like to contribute. If there is, please comment on that issue to let others know you are working on it. If there is not, please open a new issue to discuss your contribution.
5+
You should first check if there is a [GitHub issue](https://github.com/joshuadavidthomas/django-github-app/issues) already open or related to what you would like to contribute. If there is, please comment on that issue to let others know you are working on it. If there is not, please open a new issue to discuss your contribution.
66

77
Not all contributions need to start with an issue, such as typo fixes in documentation or version bumps to Python or Django that require no internal code changes, but generally, it is a good idea to open an issue first.
88

99
We adhere to Django's Code of Conduct in all interactions and expect all contributors to do the same. Please read the [Code of Conduct](https://www.djangoproject.com/conduct/) before contributing.
1010

11+
## Requirements
12+
13+
- [uv](https://github.com/astral-sh/uv) - Modern Python toolchain that handles:
14+
- Python version management and installation
15+
- Virtual environment creation and management
16+
- Fast, reliable dependency resolution and installation
17+
- Reproducible builds via lockfile
18+
- [direnv](https://github.com/direnv/direnv) (Optional) - Automatic environment variable loading
19+
- [just](https://github.com/casey/just) (Optional) - Command runner for development tasks
20+
21+
### `Justfile`
22+
23+
The repository includes a `Justfile` that provides all common development tasks with a consistent interface. Running `just` without arguments shows all available commands and their descriptions:
24+
25+
<!-- [[[cog
26+
import subprocess
27+
import cog
28+
29+
output_raw = subprocess.run(["just", "--list", "--list-submodules"], stdout=subprocess.PIPE)
30+
output_list = output_raw.stdout.decode("utf-8").split("\n")
31+
32+
cog.outl("""\
33+
```bash
34+
$ just
35+
$ # just --list --list-submodules
36+
""")
37+
38+
for i, line in enumerate(output_list):
39+
if not line:
40+
continue
41+
cog.out(line)
42+
if i < len(output_list):
43+
cog.out("\n")
44+
45+
cog.out("```")
46+
]]] -->
47+
```bash
48+
$ just
49+
$ # just --list --list-submodules
50+
51+
Available recipes:
52+
bootstrap
53+
coverage
54+
lint
55+
lock *ARGS
56+
test *ARGS
57+
testall *ARGS
58+
types *ARGS
59+
docs:
60+
build LOCATION="docs/_build/html" # Build documentation using Sphinx
61+
serve PORT="8000" # Serve documentation locally
62+
```
63+
<!-- [[[end]]] -->
64+
65+
All commands below will contain the full command as well as its `just` counterpart.
66+
1167
## Setup
1268

13-
The following setup steps assume you are using a Unix-like operating system, such as Linux or macOS, and that you have a [supported](https://django-bird.readthedocs.io/#requirements) version of Python installed. If you are using Windows, you will need to adjust the commands accordingly. If you do not have Python installed, you can visit [python.org](https://www.python.org/) for instructions on how to install it for your operating system.
69+
The following instructions will use `uv` and assume a Unix-like operating system (Linux or macOS).
70+
71+
Windows users will need to adjust commands accordingly, though the core workflow remains the same.
72+
73+
Alternatively, any Python package manager that supports installing from `pyproject.toml` ([PEP 621](https://peps.python.org/pep-0621/)) can be used. If not using `uv`, ensure you have Python installed from [python.org](https://www.python.org/).
1474

1575
1. Fork the repository and clone it locally.
16-
2. Create a virtual environment and activate it. You can use whatever tool you prefer for this. Below is an example using the Python standard library's `venv` module:
76+
2. Use `uv` too bootstrap your development environment:
1777

18-
```shell
19-
python -m venv venv
20-
source venv/bin/activate
78+
```bash
79+
uv python install
80+
uv sync --locked
81+
# just bootstrap
2182
```
2283

23-
3. Install `django-bird` and the `dev` dependencies in editable mode:
84+
This will install the correct Python version, create and configure a virtual environment, and install all dependencies.
85+
86+
## Tests
2487

25-
```shell
26-
python -m pip install --editable '.[dev]'
27-
# or using [just](#just)
28-
just bootstrap
88+
The project uses [`pytest`](https://docs.pytest.org/) for testing and [`nox`](https://nox.thea.codes/) to run the tests in multiple environments.
89+
90+
To run the test suite against the default versions of Python (lower bound of supported versions) and Django (lower bound of LTS versions):
91+
92+
```bash
93+
uv run nox --session test
94+
# just test
2995
```
3096

31-
## Testing
97+
To run the test suite against the entire matrix of supported versions of Python and Django:
3298

33-
We use [`pytest`](https://docs.pytest.org/) for testing and [`nox`](https://nox.thea.codes/) to run the tests in multiple environments.
99+
```bash
100+
uv run nox --session tests
101+
# just testall
102+
```
34103

35-
To run the test suite against the default versions of Python (lower bound of supported versions) and Django (lower bound of LTS versions), run:
104+
Both can be passed additional arguments that will be provided to `pytest`:
36105

37-
```shell
38-
python -m nox --session "test"
39-
# or using [just](#just)
40-
just test
106+
```bash
107+
uv run nox --session test -- -v --last-failed
108+
uv run nox --session tests -- --failed-first --maxfail=1
109+
# just test -v --last-failed
110+
# just testall --failed-first --maxfail=1
41111
```
42112

43-
To run the test suite against all supported versions of Python and Django, run:
113+
### Coverage
44114

45-
```shell
46-
python -m nox --session "tests"
47-
# or using [just](#just)
48-
just testall
115+
The project uses [`coverage.py`](https://github.com/nedbat/coverage.py) to measure code coverage and aims to maintain 100% coverage across the codebase.
116+
117+
To run the test suite and measure code coverage:
118+
119+
```bash
120+
uv run nox --session coverage
121+
# just coverage
49122
```
50123

51-
## `just`
124+
All pull requests must include tests to maintain 100% coverage. Coverage configuration can be found in the `[tools.coverage.*]` sections of [`pyproject.toml`](pyproject.toml).
125+
126+
## Linting and Formatting
52127

53-
[`just`](https://github.com/casey/just) is a command runner that is used to run common commands, similar to `make` or `invoke`. A `Justfile` is provided at the base of the repository, which contains commands for common development tasks, such as running the test suite or linting.
128+
This project enforces code quality standards using [`pre-commit`](https://github.com/pre-commit/pre-commit).
54129

55-
To see a list of all available commands, ensure `just` is installed and run the following command at the base of the repository:
130+
To run all formatters and linters:
56131

57-
```shell
58-
just
132+
```bash
133+
uv run nox --session lint
134+
# just lint
59135
```
136+
137+
The following checks are run:
138+
139+
- [ruff](https://github.com/astral-sh/ruff) - Fast Python linter and formatter
140+
- Code formatting for Python files in documentation ([blacken-docs](https://github.com/adamchainz/blacken-docs))
141+
- Django compatibility checks ([django-upgrade](https://github.com/adamchainz/django-upgrade))
142+
- TOML and YAML validation
143+
- Basic file hygiene (trailing whitespace, file endings)
144+
145+
To enable pre-commit hooks after cloning:
146+
147+
```bash
148+
uv run --with pre-commit pre-commit install
149+
```
150+
151+
Configuration for these tools can be found in:
152+
153+
- [`.pre-commit-config.yaml`](.pre-commit-config.yaml) - Pre-commit hook configuration
154+
- [`pyproject.toml`](pyproject.toml) - Ruff and other tool settings
155+
156+
## Continuous Integration
157+
158+
This project uses GitHub Actions for CI/CD. The workflows can be found in [`.github/workflows/`](.github/workflows/):
159+
160+
- [`test.yml`](.github/workflows/test.yml) - Runs on pushes to the `main` branch and on all PRs
161+
- Tests across Python/Django version matrix
162+
- Static type checking
163+
- Coverage reporting
164+
- [`release.yml`](.github/workflows/release.yml) - Runs on GitHub release creation
165+
- Runs the [`test.yml`](.github/workflows/test.yml) workflow
166+
- Builds package
167+
- Publishes to PyPI
168+
169+
PRs must pass all CI checks before being merged.

‎Justfile

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,11 @@ mod docs ".just/documentation.just"
55

66
[private]
77
default:
8-
@just --list
8+
@just --list --list-submodules
9+
10+
[private]
11+
cog:
12+
uv run --with cogapp cog -r CONTRIBUTING.md
913

1014
[private]
1115
fmt:

‎README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -390,6 +390,12 @@ GITHUB_APP = {
390390
391391
Secret used to verify webhook payloads from GitHub.
392392
393+
## Development
394+
395+
For detailed instructions on setting up a development environment and contributing to this project, see [CONTRIBUTING.md](CONTRIBUTING.md).
396+
397+
For release procedures, see [RELEASING.md](RELEASING.md).
398+
393399
## License
394400
395401
django-github-app is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.

0 commit comments

Comments
 (0)