developing.md

Development

Developing python projects associated with git-pull.com all use the same structure and workflow. At a later point these will refer to that website for documentation.

Bootstrap the project

Install and git and uv

Clone:

$ git clone https://github.com/vcs-python/vcspull.git

$ cd vcspull

Install packages:

$ uv sync --all-extras --dev

Development loop

Tests

pytest is used for tests.

Rerun on file change

via pytest-watcher (works out of the box):

$ make start

via entr(1) (requires installation):

$ make watch_test

Manual (just the command, please)

$ uv run py.test

or:

$ make test

Runtime dependency smoke test

Verify that the published wheel runs without dev/test extras:

$ uvx --isolated --reinstall --from . python scripts/runtime_dep_smoketest.py

The script imports every vcspull module and exercises each CLI sub-command with --help. There is also a pytest wrapper guarded by a dedicated marker:

$ uv run pytest -m scripts__runtime_dep_smoketest scripts/test_runtime_dep_smoketest.py

These checks are network-dependent because they rely on uvx to build the package in an isolated environment.

pytest options

PYTEST_ADDOPTS can be set in the commands below. For more information read docs.pytest.com for the latest documentation.

Verbose:

$ env PYTEST_ADDOPTS="-verbose" make start

Drop into pdb on first error:

$ env PYTEST_ADDOPTS="-x -s --pdb" make start

If you have ipython installed:

$ env PYTEST_ADDOPTS="--pdbcls=IPython.terminal.debugger:TerminalPdb" \
    make start

Documentation

sphinx is used for documentation generation. In the future this may change to docusaurus.

Default preview server: http://localhost:8022

Rerun on file change

sphinx-autobuild will automatically build the docs, it also handles launching a server, rebuilding file changes, and updating content in the browser:

$ cd docs

$ make start

If doing css adjustments:

$ make design

Rebuild docs on file change (requires entr(1)):

$ cd docs

$ make dev

If not GNU Make / no -J support, use two terminals:

$ make watch

$ make serve

Manual (just the command, please)

$ cd docs

Build:

$ make html

Launch server:

$ make serve

Linting

ruff

The project uses ruff to handle formatting, sorting imports and linting.

uv:

```console
$ uv run ruff check .
```

If you setup manually:

```console
$ ruff check .
```

```console
$ make ruff
```

```console
$ make watch_ruff
```

requires [`entr(1)`].

uv:

```console
$ uv run ruff check . --fix
```

If you setup manually:

```console
$ ruff check . --fix
```

ruff format

ruff format is used for formatting.

uv:

```console
$ uv run ruff format .
```

If you setup manually:

```console
$ ruff format .
```

```console
$ make ruff_format
```

mypy

mypy is used for static type checking.

uv:

```console
$ uv run mypy .
```

If you setup manually:

```console
$ mypy .
```

```console
$ make mypy
```

```console
$ make watch_mypy
```

requires [`entr(1)`].

See `[tool.mypy]` in pyproject.toml.

```{literalinclude} ../pyproject.toml
:language: toml
:start-at: "[tool.mypy]"
:end-before: "[tool"

```

Publishing to PyPI

uv handles virtualenv creation, package requirements, versioning, building, and publishing. Therefore there is no setup.py or requirements files.

Update __version__ in __about__.py and pyproject.toml::

git commit -m 'build(vcspull): Tag v0.1.1'
git tag v0.1.1
git push
git push --tags

GitHub Actions will detect the new git tag, and in its own workflow run uv build and push to PyPI.