Contributing¶

As an open source project, all cihai projects accept contributions through GitHub, GitLab and Codeberg. Below you will find resources on the internals of the project.

Note

This guide applies to all cihai projects, not just the cihai repo.

Cihai projects use standard conventions and patterns based on best practices in python.

To be efficient at debugging, developing, testing, documenting, etc. it helps to familiarize yourself with the tool within, independently if needed.

<cihai-project> can be assumed to be an existing or future cihai project, including cihai, cihai-cli, unihan-etl, unihan-db. See GitHub, GitLab and Codeberg.

Development environment¶

uv is a required package to develop.

$ git clone https://github.com/cihai/<cihai-project>.git

$ cd <cihai-project>

So if <cihai-project> is [cihai]:

$ git clone https://github.com/cihai/cihai.git

$ cd cihai

Install dependencies¶

$ uv sync --all-extras --dev

Makefile commands prefixed with watch_ will watch files and rerun.

Tests¶

[pytest] is used for tests.

$ uv run py.test

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

pytest options¶

For filename / test names within, examples will be for [cihai], if using a different cihai project check the filename and test names accordingly:

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

Pick a file:

$ env PYTEST_ADDOPTS="tests/test_cihai.py" uv run make start

Drop into test_cihai_version() in tests/test_cihai.py:

$ env PYTEST_ADDOPTS="-s -x -vv tests/test_cihai.py" uv run make start

Drop into test_cihai_version() in tests/test_cihai.py and stop on first error:

$ env PYTEST_ADDOPTS="-s -x -vv tests/test_cihai.py::test_cihai" uv run 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

$ make test

You probably didn’t see anything but tests scroll by.

If you found a problem or are trying to write a test, you can file an on the tracker for the relevant cihai project.

Manual invocation¶

Test only a file:

$ py.test tests/test_cihai.py

will test the tests/test_cihai.py tests.

$ py.test tests/test_cihai.py::test_cihai_version

tests test_cihai_version() inside of tests/test_cihai.py.

Multiple can be separated by spaces:

$ py.test tests/test_{conversion,exc}.py tests/test_config.py::test_configurator

Documentation¶

sphinx-autobuild will automatically build the docs, watch for file changes and launch a server.

From home directory: make start_docs From inside docs/: make start

Manual documentation (the hard way)¶

cd docs/ and make html to build. make serve to start http server.

Helpers: make build_docs, make serve_docs

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

Rebuild docs and run server via one terminal: make dev_docs (requires above, and a make(1) with -J support, e.g. GNU Make)

View documentation locally¶

To find the URL of the preview server, read the terminal, the URL may very depending on the project! An example of what to look for:

[I 220816 14:43:41 server:335] Serving on http://127.0.0.1:8035

Formatting / Linting¶

black¶

black is used for formatting.

Command

uv:

$ uv run black .

If you setup manually:

$ black .

make

$ make black

In the future, ruff (below) may replace black as formatter.

ruff¶

The project uses ruff to handle sorting imports and linting.

Command

uv:

$ uv run ruff

If you setup manually:

$ ruff check .

make

$ make ruff

Watch

$ make watch_ruff

requires entr(1).

Fix files

uv:

$ uv run ruff check . --fix

If you setup manually:

$ ruff check . --fix

mypy¶

mypy is used for static type checking.

Command

uv:

$ uv run mypy .

If you setup manually:

$ mypy .

make

$ make mypy

Watch

$ make watch_mypy

requires entr(1).

Releasing¶

Since this software used in production projects, we don’t release breaking changes until there’s a major feature release.

Choose what the next version is. Assuming it’s version 0.9.0, it could be:

0.9.0post0: postrelease, if there was a packaging issue
0.9.1: bugfix / security / tweak
0.10.0: breaking changes, new features

Let’s assume we pick 0.9.1

CHANGES: Assure any PRs merged since last release are mentioned. Give a thank you to the contributor. Set the header with the new version and the date. Leave the “current” header and Insert changes/features/fixes for next release here at the top:

## package-name 0.10.x (unreleased)

- _Insert changes/features/fixes for next release here_

## package-name 0.9.1 (2020-10-12)

- :issue:`1`: Fix bug

package_name/__init__.py and __about__.py - Set version

$ git commit -m 'Tag v0.9.1'

$ git push

Important: Create and push the tag. Make sure the version is correct and the pyproject.toml and __about__.py match the version being deployed.

$ git tag v0.9.1

$ git push --tags

Automated deployment¶

CI will automatically push to the PyPI index when a tag is pushed.

Manual deployment¶

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(cihai): 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.