Skip to content

Development

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .

The frontend is plain HTML, CSS and ES modules in src/cc_calendar/static/, with no build step. Tests use synthetic logs only; never commit real transcripts.

Screenshots

The screenshots are rendered from fictional data generated by scripts/demo_data.py, including its notes and tags. They use your installed Google Chrome and leave your own notes and search index alone:

uv run --with playwright python scripts/screenshots.py

This site

This site is built with Zensical from docs/ and zensical.toml. GitHub Actions deploys it to GitHub Pages on pushes to main that change the site (docs/, zensical.toml, pyproject.toml or uv.lock).

Preview it locally:

uv run --group docs zensical serve

The Japanese pages live in docs/ja/ and are built with zensical.ja.toml into site/ja, served at /cc-calendar/ja/. When you change an English page, update the matching docs/ja/ page in the same pull request. Keep its { #anchor } heading ids identical to the English slugs, and reference images as ../images/…; tests/test_docs.py checks both. To build both sites locally:

uv run --group docs zensical build --clean
uv run --group docs zensical build -f zensical.ja.toml

Releasing

Pushing a version tag publishes the package to PyPI through .github/workflows/release.yml:

  1. Bump the version on main (it lives in pyproject.toml only) and merge it:

    uv version --bump minor   # or --bump patch, or uv version 1.2.3
    
  2. Tag the merged commit and push the tag:

    git tag v1.2.3
    git push origin v1.2.3
    

The workflow checks that the tag matches the version, runs the lint and tests, builds the wheel and sdist, and smoke-tests the wheel. It then publishes to PyPI with trusted publishing (the pypi environment) and attaches the files to the GitHub release. It creates the release as a draft if it does not exist yet, so you can write the release notes and publish it.

PyPI does not accept the same version twice. If publishing fails after the upload, bump the version again instead of moving the tag.

Acknowledgements

Inspired by the tool shown in this post by @tokkyo. This is an independent reimplementation and is not affiliated with the original.