Skip to content

README-dev.md

Latest commit

 

History

History
170 lines (114 loc) · 4.93 KB

README-dev.md

File metadata and controls

170 lines (114 loc) · 4.93 KB
Raw

Pycliche developer README

Develop

Development prerequisites

In addition to the Prerequisites listed in the README you will need the following to develop pycliche:

Recursive pycliche

The pycliche repo has been retrofit to use pycliche itself as its template following release v2.6.0.

To update pycliche to a newer version of itself:

cd ~/Projects/pycliche/
uvx copier update --skip-answered --trust [--vcs-ref=<TAG>]

If the --vcs-ref flag is not specified, copier will use the latest pycliche tag.

Git principles

This repo follows trunk-based development. This means:

  • the main branch should always be in a releasable state
  • use short-lived feature branches

Dependency management

Dependencies are defined in the pyproject.toml file. uv is used to manage dependencies:

# add a dependency to the project
uv add some-package

Updating dependencies in the template

There are two places where dependencies are currently declared in the template:

  1. prek.toml
  2. pyproject.toml.jinja

Update git hooks in the former via:

cd template/ && prek autoupdate

Update Python packages in the latter manually. Automated option pending on account of commands like uv lock --upgrade-package not taking kindly to Jinja templates.

Generate project using development version

When developing pycliche it is useful to observe the outcome of generating new projects that use in-progress features. To do so:

# navigate to the parent directory of your local copy of pycliche
cd ~/Projects/
# vcs-ref flag to use the latest local version of pycliche instead of a tagged version
uvx copier copy --vcs-ref=HEAD pycliche $TEST_PROJECT_NAME

Style

Code style is enforced by prek pre-commit hooks. Linter rules are configured in the ruff tables in pyproject.toml.

# before you start developing, install pre-commit hooks
prek install

# update pre-commit hooks
prek autoupdate

Docstrings should follow the conventions set out in the Google styleguide.

Please follow the Conventional Commits guidelines when writing commit messages. commitlint is enabled as a pre-commit hook. Valid commit types are defined in .commitlintrc.ts.

Test

# Run all `pytest` tests (in parallel by default)
nox

# Run tests with the debugger enabled (serial execution due to `pdb`)
nox -- --pdb

By default this will only run the nox session for the latest supported Python release.

To run all nox sessions (ie. for all supported Python releases):

nox -k tests

Pass flags as you normally would to pytest by placing them after -- eg.

nox -- -k some_keyword_expression

Tests have marks, allowing you to run only a subset:

nox -- -m unit
# or
nox -- -m "not smoke"

See the tool.pytest table in pyproject.toml for a list of all marks.

Nox is used to automate testing across different Python versions. Test sessions are configured via noxfile.py.

Tests in GitHub Actions

A matrix strategy is used for the test GitHub Action. This runs each Nox session (i.e. Python version test run) as a separate pipeline job.

Release

Release Please is used to automate:

  • Updating the changelog.
  • Calculating the new SemVer tag based on conventional commit types.
  • Creating a new GitHub release.

Release Please is configured as a GitHub action (release-please.yaml). It keeps a release pull request open that is refreshed as changes are merged into main. To cut a release, simply merge the release pull request.

GitHub Personal Access Token

In order for Release Please to automate the above process, a GitHub Actions secret called PYCLICHE_RELEASE_PLEASE_TOKEN must exist in GitHub (albertomh/pycliche/settings/secrets/actions). The contents of this secret must be a Personal Access Token (PAT) with the following permissions:

contents: write
pull-requests: write

For more information, consult the release-please-action project.

Record demo

The main README includes a GIF showcasing generating a project using pycliche. To record a new demo, record the output of running docs/media/auto_pycliche_demo.sh.

Convert to a gif with:

# speed up video by 2x (PTS/2)
ffmpeg -i pycliche-M.m.p-demo.mov -filter:v "setpts=PTS/2,fps=60" -an pycliche-M.m.p-demo_fast.mov
# convert to GIF
ffmpeg -i pycliche-M.m.p-demo_fast.mov -vf "fps=15,scale=iw:-1:flags=lanczos" -loop 0 pycliche-M.m.p-demo.gif