117 lines
2.9 KiB
Markdown
117 lines
2.9 KiB
Markdown
# Workflow
|
|
|
|
This page describes the tooling used during development of this project. It also
|
|
serves as a reference for the various commands that you would use when working
|
|
on this project.
|
|
|
|
## Overview
|
|
|
|
This project uses the [GitHub Flow] for collaboration. The codebase is Python.
|
|
|
|
- [flit] is used for automating development tasks.
|
|
- [nox] is used for automating development tasks.
|
|
- [pre-commit] is used for running the linters.
|
|
- [sphinx] is used for generating this documentation.
|
|
- [pytest] is used for running the automated tests.
|
|
|
|
## Repository Layout
|
|
|
|
The repository layout is pretty standard for a modern pure-Python project.
|
|
|
|
- `CODE_OF_CONDUCT.md`
|
|
- `LICENSE`
|
|
- `README.md`
|
|
- `.nox/` -- Generated by [nox].
|
|
- `dist/` -- Generated as part of the release process.
|
|
- `docs/` -- Sources for the documentation.
|
|
- `src/`
|
|
- `installer/` -- Actual source code for the package
|
|
- `tests/` -- Automated tests for the package.
|
|
- `noxfile.py` -- for [nox].
|
|
- `pyproject.toml` -- for packaging and tooling configuration.
|
|
|
|
## Initial Setup
|
|
|
|
To work on this project, you need to have git 2.17+ and Python 3.7+.
|
|
|
|
- Clone this project using git:
|
|
|
|
```sh
|
|
git clone https://github.com/pradyunsg/installer.git
|
|
cd installer
|
|
```
|
|
|
|
- Install the project's main development dependencies:
|
|
|
|
```sh
|
|
pip install nox
|
|
```
|
|
|
|
You're all set for working on this project.
|
|
|
|
## Commands
|
|
|
|
### Code Linting
|
|
|
|
```sh
|
|
nox -s lint
|
|
```
|
|
|
|
Run the linters, as configured with [pre-commit].
|
|
|
|
### Testing
|
|
|
|
```sh
|
|
nox -s test
|
|
```
|
|
|
|
Run the tests against all supported Python versions, if an interpreter for that
|
|
version is available locally.
|
|
|
|
```sh
|
|
nox -s test-3.9
|
|
```
|
|
|
|
Run the tests against Python 3.9. It is also possible to specify other supported
|
|
Python versions (like `3.7` or `pypy3`).
|
|
|
|
### Documentation
|
|
|
|
```sh
|
|
nox -s docs
|
|
```
|
|
|
|
Generate the documentation for installer into the `build/docs` folder. This
|
|
(mostly) does the same thing as `nox -s docs-live`, except it invokes
|
|
`sphinx-build` instead of [sphinx-autobuild].
|
|
|
|
```sh
|
|
nox -s docs-live
|
|
```
|
|
|
|
Serve this project's documentation locally, using [sphinx-autobuild]. This will
|
|
open the generated documentation page in your browser.
|
|
|
|
The server also watches for changes made to the documentation (`docs/`), which
|
|
will trigger a rebuild. Once the build is completed, server will automagically
|
|
reload any open pages using livereload.
|
|
|
|
## Release process
|
|
|
|
- Update the changelog.
|
|
- Update the version number in `__init__.py`.
|
|
- Commit these changes.
|
|
- Create a signed git tag.
|
|
- Run `flit publish`.
|
|
- Update the version number in `__init__.py`.
|
|
- Commit these changes.
|
|
- Push tag and commits.
|
|
|
|
[github flow]: https://guides.github.com/introduction/flow/
|
|
[flit]: https://flit.readthedocs.io/en/stable/
|
|
[nox]: https://nox.readthedocs.io/en/stable/
|
|
[pytest]: https://docs.pytest.org/en/stable/
|
|
[sphinx]: https://www.sphinx-doc.org/en/master/
|
|
[sphinx-autobuild]: https://github.com/executablebooks/sphinx-autobuild
|
|
[pre-commit]: https://pre-commit.com/
|