psi-jack/dotbot
1
0
Fork 0
mirror of synced 2025-01-23 12:10:28 -05:00
Code Issues Releases Wiki Activity

Add development guide

Browse source
This commit is contained in:
Anish Athalye 2025-01-04 07:13:37 -08:00
parent b8891c5fb7
commit 9cd5d073f2
2 changed files with 79 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

43
CONTRIBUTING.md
View file

@ -44,43 +44,11 @@ describing what you intend to work on.
Any changes to the code base should follow the style and coding conventions
used in the rest of the project. The version history should be clean, and
commit messages should be descriptive and [properly
formatted][commit-messages].
formatted][commit-messages]. It's recommended that you add unit tests to
demonstrate that the bug is fixed (or that the feature works).
### Testing
When preparing a patch, it's recommended that you add unit tests
that demonstrate the bug is fixed (or that the feature works). You
can run tests on your local machine using [Hatch][hatch]:
```bash
hatch test
```
If you prefer to run the tests in an isolated container using Docker, you can
do so with the following:
```bash
docker run -it --rm -v "${PWD}:/dotbot" -w /dotbot python:3.13-bookworm /bin/bash
```
After spawning the container, install Hatch with `pip install hatch`, and then
run the tests.
### Type checking
You can run type checking with:
```bash
hatch run types:check
```
### Formatting and linting
You can run the [Ruff][ruff] formatter and linter with:
```bash
hatch fmt
```
See the [Dotbot development guide][development] to learn how to run the tests,
type checking, and more.
---
@ -91,5 +59,4 @@ If you have any questions about anything, feel free to [ask][email]!
[fork]: https://github.com/anishathalye/dotbot/fork
[email]: mailto:me@anishathalye.com
[commit-messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
[hatch]: https://hatch.pypa.io/
[ruff]: https://github.com/astral-sh/ruff
[development]: DEVELOPMENT.md

74
DEVELOPMENT.md Normal file
View file

@ -0,0 +1,74 @@
# Development
Dotbot uses the [Hatch] project manager ([installation instructions][hatch-install]).
Hatch automatically manages dependencies and runs testing, type checking, and other operations in isolated [environments][hatch-environments].
[Hatch]: https://hatch.pypa.io/
[hatch-install]: https://hatch.pypa.io/latest/install/
[hatch-environments]: https://hatch.pypa.io/latest/environment/
## Testing
You can run the tests on your local machine with:
```bash
hatch test
```
The [`test` command][hatch-test] supports options such as `-c` for measuring test coverage, `-a` for testing with a matrix of Python versions, and appending an argument like `tests/test_shell.py::test_shell_can_override_defaults` for running a single test.
[hatch-test]: https://hatch.pypa.io/latest/tutorials/testing/overview/
### Isolation
Dotbot executes shell commands and interacts with the filesystem, and the tests exercise this functionality. The tests try to [insulate][dotbot-conftest] themselves from the machine, but if you prefer to run tests in an isolated container using Docker, you can do so with the following:
```bash
docker run -it --rm -v "${PWD}:/dotbot" -w /dotbot python:3.13-bookworm /bin/bash
```
After spawning the container, install Hatch with `pip install hatch`, and then run the tests as described above.
[dotbot-conftest]: tests/conftest.py
## Type checking
You can run the [mypy static type checker][mypy] with:
```bash
hatch run types:check
```
[mypy]: https://mypy-lang.org/
## Formatting and linting
You can run the [Ruff][ruff] formatter and linter with:
```bash
hatch fmt
```
This will automatically make [safe fixes][fix-safety] to your code. If you want to only check your files without making modifications, run `hatch fmt --check`.
[ruff]: https://github.com/astral-sh/ruff
[fix-safety]: https://docs.astral.sh/ruff/linter/#fix-safety
## Packaging
You can use [`hatch build`][hatch-build] to create build artifacts, a [source distribution ("sdist")][sdist] and a [built distribution ("wheel")][bdist].
You can use [`hatch publish`][hatch-publish] to publish build artifacts to [PyPI][pypi].
[hatch-build]: https://hatch.pypa.io/latest/build/
[sdist]: https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist
[bdist]: https://packaging.python.org/en/latest/glossary/#term-Built-Distribution
[hatch-publish]: https://hatch.pypa.io/latest/publish/
[pypi]: https://pypi.org/
## Continuous integration
Testing, type checking, and formatting/linting is [checked in CI][ci].
[ci]: .github/workflows/ci.yml