====================================== Tests / Docs / MyPy / Package Building ====================================== Clone the repository -------------------- Get the source code using the following command: .. code-block:: sh $ git clone https://github.com/ephes/django-resume.git Switch to the django-resume directory: .. code-block:: sh $ cd django-resume Install the pre-commit hooks ---------------------------- .. code-block:: sh $ uvx run pre-commit install Install the Package using uv ---------------------------- .. code-block:: sh $ uv sync --dev Repository Checks ----------------- Show the available ``just`` commands with: .. code-block:: sh $ just Run the full local validation suite with: .. code-block:: sh $ 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: .. code-block:: sh $ just loc Run the Example Project ----------------------- Start the example Django project with: .. code-block:: sh $ just serve-example Run the Migrations ------------------ .. code-block:: sh $ uv run python manage.py migrate Run the Python Tests -------------------- .. code-block:: sh $ uv run pytest Coverage -------- .. code-block:: sh $ uv run coverage run -m pytest $ uv run coverage report Run the Static Analysis ----------------------- .. code-block:: sh $ uv run mypy src Install the JavaScript Dependencies ----------------------------------- .. code-block:: sh $ npm install Run the JavaScript Tests ------------------------ .. code-block:: sh $ npx vitest run End to End Tests ---------------- Install browsers for playwright: .. code-block:: sh $ playwright install Create a testuser for the e2e tests user, using the password `password`: .. code-block:: sh $ 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): .. code-block:: sh $ 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: .. code-block:: sh $ uv run pytest e2e_tests Run playwright tests in head-full mode: .. code-block:: sh $ uv run pytest e2e_tests --headed --slowmo 1000 Cleanup the test database after running the tests: .. code-block:: sh $ 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: .. code-block:: sh $ make -C docs clean $ make -C docs html The documentation will be available in the `docs/_build/html` directory: .. code-block:: sh $ open docs/_build/html/index.html Serve the built documentation locally with: .. code-block:: sh $ just docs-serve Pass a custom port as the first argument when needed: .. code-block:: sh $ just docs-serve 9000 Update Javascript Dependencies ------------------------------ Check with `npm outdated` if there are any outdated dependencies. If there are, update them: .. code-block:: sh $ 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``. 1. Start from a clean worktree: .. code-block:: sh $ git status --short 2. 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. 3. Update the version number in: - ``pyproject.toml`` - ``docs/conf.py`` 4. 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. 5. Run the release validation gates: .. code-block:: sh $ just check $ make -C docs html 6. Clean old package artifacts and build the package. .. admonition:: 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. .. code-block:: sh $ rm -rf dist/ $ uv build --wheel $ uv build --sdist 7. Validate the package artifacts: .. code-block:: sh $ uvx twine check dist/django_resume-*.whl dist/django_resume-*.tar.gz 8. Commit the release prep changes: .. code-block:: sh $ git add pyproject.toml docs/conf.py docs/changelog.txt $ git commit -m "Release X.Y.Z" 9. Create an annotated release tag: Older releases used lightweight tags. Use annotated tags for new releases so the release metadata is explicit. .. code-block:: sh $ git tag -a X.Y.Z -m "Release version X.Y.Z" 10. Publish the package to ``pypi.org``: .. code-block:: sh $ uv publish --token your_token 11. Push the release commit and tag: .. code-block:: sh $ git push $ git push origin X.Y.Z 12. 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: .. code-block:: sh $ 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.