# 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)
```