122 lines
2.4 KiB
Markdown
122 lines
2.4 KiB
Markdown
# Development
|
|
|
|
> All changes MUST follow the vendor/tiara-gitflow-spec.git and no work MUST be
|
|
> started without a TODO issue.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.9+
|
|
- [Pipenv](https://pipenv.pypa.io/)
|
|
- [tox](https://tox.wiki/) (installed via Pipenv dev dependencies)
|
|
- Node.js (for the `@byteb4rb1e/mime-todo` issue tracker CLI)
|
|
|
|
## Setup
|
|
|
|
Iniitialize Git submodules:
|
|
|
|
```bash
|
|
git submodule update --init --remote --recursive
|
|
```
|
|
|
|
Install dependencies (includes the package in editable mode):
|
|
|
|
```bash
|
|
pipenv install --dev
|
|
```
|
|
|
|
|
|
## Tooling
|
|
|
|
### Package
|
|
|
|
The project is packaged as `byteb4rb1e.utils` under a namespace package
|
|
layout (`src/byteb4rb1e/utils/`). It is installed in editable mode via
|
|
Pipenv.
|
|
|
|
Build a distribution:
|
|
|
|
```bash
|
|
pipenv run dist
|
|
```
|
|
|
|
### Testing
|
|
|
|
Tests are managed by tox. Test environments are defined in `tox.ini`:
|
|
|
|
```bash
|
|
# run all test suites
|
|
tox
|
|
|
|
# run specific environments
|
|
tox -e unit-py313
|
|
tox -e lint
|
|
tox -e format
|
|
```
|
|
|
|
| Environment | Purpose |
|
|
|---|---|
|
|
| `unit-py3{9-13}` | Unit tests |
|
|
| `smoke-py3{9-13}` | Smoke tests |
|
|
| `integration-py3{9-13}` | Integration tests |
|
|
| `lint` | Type checking (mypy) |
|
|
| `format` | Code style (autopep8) |
|
|
| `audit` | Dependency audit (pip-audit) |
|
|
|
|
### Issue tracker
|
|
|
|
Issues are tracked in the `TODO` file using the
|
|
[MIME TODO](https://specs.code.tiararodney.com/mime-todo/) format. Use the
|
|
`@byteb4rb1e/mime-todo` CLI to interact with it:
|
|
|
|
```bash
|
|
# list issues
|
|
npx @byteb4rb1e/mime-todo list
|
|
|
|
# show a specific issue
|
|
npx @byteb4rb1e/mime-todo show 3
|
|
|
|
# create an issue
|
|
npx @byteb4rb1e/mime-todo create --type feature --title "Title" --plan "Description" --module homeostat
|
|
```
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full issue lifecycle.
|
|
|
|
### Publishing
|
|
|
|
Build wheel and source distributions:
|
|
|
|
```sh
|
|
pipenv run sdist
|
|
```
|
|
|
|
Configure publishing options:
|
|
|
|
`~/.pypirc`
|
|
```
|
|
[distutils]
|
|
index-servers =
|
|
tiararodney
|
|
|
|
[tiararodney]
|
|
repository: https://pypi.code.tiararodney.com/root/byteb4rb1e/
|
|
username: <username>
|
|
password: <password>
|
|
```
|
|
|
|
Publish to pypi.code.tiararodney.com:
|
|
|
|
```sh
|
|
pipenv run sdist:publish:tiarardoney
|
|
```
|
|
|
|
|
|
## Project layout
|
|
|
|
```
|
|
src/byteb4rb1e/utils/ # package source
|
|
tests/ # test suites (unit/, smoke/, integration/)
|
|
vendor/ # vendored specs
|
|
dist/ # sdist and wheel build output
|
|
DEVELOPMENT.md # this file
|
|
TODO # issue tracker (MIME TODO format)
|
|
```
|