Add development guide

CONTRIBUTING.md

@@ -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
+See the [Dotbot development guide][development] to learn how to run the tests,
-
+type checking, and more.
-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
-```
 
 ---
 
@@ -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/
+[development]: DEVELOPMENT.md
-[ruff]: https://github.com/astral-sh/ruff

DEVELOPMENT.md

@@ -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