Djereo developer documentation

This page covers how to Develop, Test, Document and Release changes to djereo itself.

Develop

djereo's source code can be found at https://github.com/albertomh/djereo.

Development prerequisites

In addition to the prerequisites listed in the Quickstart you will need the following to develop djereo:

Upgrading the pycliche version

djereo is built on top of the pycliche Python project template. To update djereo to a newer version of pycliche:

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

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

Using the pycliche repo as a git remote

Alternatively, since djereo was started by cloning pycliche v2.10.0, the latest changes to pycliche may be brought in as follows:

# ensure pycliche exists as an upstream remote repo

git remote -v
# expected output:
#     origin  git@github.com:albertomh/djereo.git (fetch)
#     origin  git@github.com:albertomh/djereo.git (push)
#     upstream        git@github.com:albertomh/pycliche.git (fetch)
#     upstream        git@github.com:albertomh/pycliche.git (push)

# if not present, add pycliche as a remote
git remote add upstream https://github.com:albertomh/pycliche.git

# fetch the latest changes from pycliche
git fetch upstream

# merge pycliche changes into djereo
# flag necessary since the repos' histories diverged
git merge --allow-unrelated-histories upstream/<branch-or-tag>

# resolve conflicts manually, if any
# stage resolved changes and finish the merge with
git commit

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

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.

N.B.
The phrase "gen. project" is used frequently in commit messages. It means "generated project", i.e. the repository created by invoking copier with the djereo template as documented in the Quickstart.

N.B.
The commit type feat(docs) (and similarly scoped feats) may seem unconventional at first glance. This is used occasionally in djereo's commit messages to indicate that the work relates to the documentation (eg. README.md) included in generated projects. It is a feature of djereo which relates to documentation.

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. .pre-commit-config.yaml.jinja
  2. pyproject.toml.jinja

Update git hooks in the former via:

cd template/ && pre-commit 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 djereo 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 djereo
cd ..
# vcs-ref flag to use the latest local version of djereo instead of a tagged version
uvx copier copy --vcs-ref=HEAD djereo $TEST_PROJECT_NAME

Style

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

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

# update pre-commit hooks
pre-commit autoupdate

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

Upgrade checklist

  1. Check Django releases and update the django_version question in copier.yaml.

Test

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

Run all tests using pytest with:

nox

Run only a given module:

nox [--session tests-3.13] -- -k test_validators

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

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

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

Tests in GitHub Actions

The test job in GitHub Actions uses the matrix strategy. This runs each Nox session (i.e. Python version test run) as a separate pipeline job.

Document

djereo's documentation is published as a static site generated using mkdocs.

Source markdown and configuration live in the docs/ directory. The docs are styled using the readthedocs theme.

To view the docs when developing locally run the recipe:

# from the `docs/` directory
just serve

and navigate to http://127.0.0.1:8001/.

A custom GitHub action (.github/actions/publish-docs) builds the mkdocs site and publishes it to the gh-pages branch. Changes to this branch are automatically deployed to https://albertomh.github.io/djereo/.

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 DJEREO_RELEASE_PLEASE_TOKEN must exist in GitHub (albertomh/djereo/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).