Package Building¶

Clone the repository¶

Get the source code using the following command:

$ git clone https://github.com/ephes/django-resume.git

Switch to the django-resume directory:

$ cd django-resume

Install the pre-commit hooks¶

$ uvx run pre-commit install

Install the Package using uv¶

$ uv sync --dev

Repository Checks¶

Show the available just commands with:

$ just

Run the full local validation suite with:

$ just check

Line Count Overview¶

Show a colorized repository line-count summary with language totals, a high-level src vs tests overview, and a directory breakdown:

$ just loc

Run the Example Project¶

Start the example Django project with:

$ just serve-example

Run the Migrations¶

$ uv run python manage.py migrate

Run the Python Tests¶

$ uv run pytest

Coverage¶

$ uv run coverage run -m pytest
$ uv run coverage report

Run the Static Analysis¶

$ uv run mypy src

Install the JavaScript Dependencies¶

$ npm install

Run the JavaScript Tests¶

$ npx vitest run

End to End Tests¶

Install browsers for playwright:

$ playwright install

Create a testuser for the e2e tests user, using the password password:

$ DJANGO_SUPERUSER_USERNAME=playwright \
  DJANGO_SUPERUSER_EMAIL=playwright@example.com \
  DJANGO_SUPERUSER_PASSWORD=password \
  uv run python manage.py createsuperuser --noinput

Start the development server like this to use the playwright settings (mainly setting DEBUG = True to have the static files served by Django):

$ uv run python manage.py runserver 0.0.0.0:8000 --settings=tests.playwright_settings

The base_url is set via tool.pytest.ini_options in pyproject.toml.

Run the e2e tests with:

$ uv run pytest e2e_tests

Run playwright tests in head-full mode:

$ uv run pytest e2e_tests --headed --slowmo 1000

Cleanup the test database after running the tests:

$ uv run python manage.py remove_all_resumes

Build the Documentation¶

The documentation is built using Sphinx with the furo theme. To build the documentation, run the following commands:

$ make -C docs clean
$ make -C docs html

The documentation will be available in the docs/_build/html directory:

$ open docs/_build/html/index.html

Serve the built documentation locally with:

$ just docs-serve

Pass a custom port as the first argument when needed:

$ just docs-serve 9000

Update Javascript Dependencies¶

Check with npm outdated if there are any outdated dependencies. If there are, update them:

$ npm update

Release Process¶

Use this checklist when preparing a package release. The project currently releases from main and uses plain version-number git tags, for example 0.1.14.

Start from a clean worktree:
```
$ git status --short
```
Choose the next version number.

Use a patch release for small fixes. Use a minor release when the Unreleased changelog contains breaking changes or larger feature work.
Update the version number in:
- pyproject.toml
- docs/conf.py
Update docs/changelog.txt:
- Move the current Unreleased entries under a new X.Y.Z - YYYY-MM-DD heading, and match the underline length to the heading text.
- Leave a fresh Unreleased section above the new release entry. The fresh section should look like:
```
Unreleased
----------
```
- Keep breaking changes, features, and fixes grouped under the release where applicable.
Run the release validation gates:
```
$ just check
$ make -C docs html
```
Clean old package artifacts and build the package.

wheel/sdist issues

uv build will build both a wheel and a sdist. But the wheel will be empty. To build a wheel with the correct content, you need to run uv build --wheel and uv build --sdist separately.
```
$ rm -rf dist/
$ uv build --wheel
$ uv build --sdist
```

Validate the package artifacts:

$ uvx twine check dist/django_resume-*.whl dist/django_resume-*.tar.gz

Commit the release prep changes:

$ git add pyproject.toml docs/conf.py docs/changelog.txt
$ git commit -m "Release X.Y.Z"

Create an annotated release tag:

Older releases used lightweight tags. Use annotated tags for new releases so the release metadata is explicit.
```
$ git tag -a X.Y.Z -m "Release version X.Y.Z"
```
Publish the package to pypi.org:
```
$ uv publish --token your_token
```
Push the release commit and tag:
```
$ git push
$ git push origin X.Y.Z
```

Create a GitHub release from the pushed tag and upload the checked package artifacts. Use the release section from docs/changelog.txt as the release notes, for example via a temporary release-notes.md file:

$ gh release create X.Y.Z \
      dist/django_resume-X.Y.Z-py3-none-any.whl \
      dist/django_resume-X.Y.Z.tar.gz \
      --verify-tag \
      --title "X.Y.Z" \
      --notes-file release-notes.md

Publishing, pushing, and creating GitHub releases are maintainer actions. Agents preparing a release should stop after validation and artifact generation, then report the remaining uv publish, git push, and gh release create commands for the maintainer to run.