publish with uv - close #34

Author: peterfarrell

.coveragerc

@@ -5,5 +5,4 @@ source = herald
 branch = True
 omit =
     */migrations/*
-    */tests/*
-    runtests.py
+    */tests/*

.github/workflows/ci.yml

@@ -40,5 +40,6 @@ jobs:
     - name: Run tests
       run: |
         uv run coverage run --source herald runtests.py -v 2
+        uv run coverage run -m django test --settings=tests.settings --pythonpath=. -v 2
     - name: Report coverage to Codecov
       uses: codecov/codecov-action@v3

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - #35 via MR #36 - Add security policy via `SECURITY.md`
 - #33 via MR #38 - Switch to `uv` for package dependencies
+- #34 - Switch to `uv` for building and publishing package
 - Chore/Docs: Drop official support for Python 3.9 (EOL October 2025)
 
 

CONTRIBUTING.md

@@ -45,12 +45,25 @@
 
 ## Running Tests
 
-This will run with a SQLite3 in-memory database:
+This will run tests with a SQLite3 in-memory database and coverage:
+```bash
+uv run coverage run -m django test --settings=tests.settings --pythonpath=. -v 2
+```
 
+* `--pythonpath=.` is required to set the context otherwise you will recieve the error `ModuleNotFoundError: No module named 'tests'`
+* `-v 3` sets the verbosity high enough to be able to see pre-migrate handlers, migrations, and post-migrate handlers.
+
+Show the coverage report to gain feedback on missing test case coverage:
 ```bash
-uv run runtests.py -v 2
+uv run coverage report --show-missing
 ```
 
+### Supported environment variables for tests
+
+| Environment Name | Description | Default Value |
+| ----- | ----- | ----- |
+| `HERALD_TEST_DB_NAME` | The path and name to the SQLite DB name. | `db.sqlite3` |
+
 ## Running Server to See Views
 
 You will need to run migrations:
@@ -61,4 +74,6 @@ uv run manage.py migrate
 Run server:
 ```bash
 uv run manage.py runserver 0.0.0.0:8000
-```
+```
+
+Open a browser to: [http://localhost:8000/](http://localhost:8000)

MANIFEST.in

@@ -1,4 +1,4 @@
-# django-heralder
+# Django Heralder
 
 [![Latest PyPI version](https://badge.fury.io/py/django-heralder.svg)](https://pypi.python.org/pypi/django-heralder)
 [![Tests](https://github.com/peterfarrell/django-heralder/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/peterfarrell/django-heralder/actions/workflows/ci.yml)
@@ -28,26 +28,30 @@ As of Django-Heralder `v0.4.0`, Django-Heralder has diverged from original proje
 
 ### Supported Django / Python Versions
 
-We try to make Heralder support all versions of django that django supports + all versions in between. 
+We try to make Heralder support all versions of LTS that Django supports + all versions in between. 
 
 For python, Heralder supports all versions of python that the above versions of django support.
 
-As of Heralder v0.4.0, we support:
+We currently support:
 
 | Django | Python `3.10` | Python `3.11` | Python `3.12` | Python `3.13` |
-| --- | --- | --- | --- | --- | --- |
+| --- | --- | --- | --- | --- |
 | `3.2.x` | **Y** | - | - | - |
 | `4.2.x` | **Y** | **Y** | **Y** | - |
 | `5.2.x` | **Y** | **Y** | **Y** | **Y** |
 
 ### Installation
 
-1. Install Django-Heralder using your favority packagement management tool (e.g. `pip`, `uv`, etc.)
+1. Install Django Heralder using your favority packagement management tool (e.g. `pip`, `uv`, etc.)
 
     ```bash
     pip install django-heralder
     ```
 
+    ```bash
+    uv add django-heralder
+    ```
+
 2. In your `settings.py` file, add `herald` and `django.contrib.sites` to `INSTALLED_APPS`:
 
     ```python

README.md

@@ -1,34 +1,82 @@
-# How to Release
+# How to Build and Publish the Package to PyPi
 
-## Prerequistics
+Django Heralder uses UV to build and publish the package.
 
-1. Install `setuptools` and `twine`:
+## How to Choose a Version Number
+
+This library uses [Semantic Versioning (semver)](https://semver.org/), meaning versions follow the `MAJOR.MINOR.PATCH` format.
+
+```
+1.2.3
+^ ^ ^
+| | |
+| | | ------- Patch
+| | --------- Minor
+```
+
+Given a version number MAJOR.MINOR.PATCH, increment the:
+
+| Version Type | Example Version | Compatibility | Description |
+| ----- | ----- | ----- | ----- |
+| **PATCH** | `1.2.4` | Backward-compatible | Increment for bug fixes and minor, **backward-compatible** improvements. This includes documentation updates. |
+| **MINOR** | `1.3.0`| Backward-compatible | Increment for new features or improvements in a **backward-compatible** manner. |
+| **MAJOR** | `2.0.0` | Breaking changes (incompatible) | Increment for **breaking changes (incompatible)** that require engineers to modify their applications. This signals a significant release.|
+
+When incrementing the:
+
+* **MAJOR:** Reset the both **MINOR** to` 0` and **PATCH** to `0`
+    * Ex: `1.8.9` becomes `2.0.0`
+* **MINOR:** Reset the **PATCH** to `0`
+    * Ex: `1.8.9` becomes `1.9.0`
+
+## Publish Package Using UV
+
+### Manual
+
+1. Update the `CHANGELOG.md` file.  Move any `[Unreleased]` items into a version using an appropriate SemVer version (see above).
+2. Bump the version number in the `pyproject.toml` using the `uv version` command below by providing a positional arugment. This is update the `pyproject.toml` file.
 
     ```bash
-    pip install setuptools twine
+    uv version 0.5.1
+    >> Resolved 31 packages in 346ms
+    >>     Built django-heralder @ file:///Users/django/Projects/django-heralder
+    >> Prepared 1 package in 725ms
+    >> Uninstalled 1 package in 1ms
+    >> Installed 1 package in 3ms
+    >> - django-heralder==0.5.0 (from file:///Users/django/Projects/django-heralder)
+    >> + django-heralder==0.5.1 (from file:///Users/django/Projects/django-heralder)
+    >> django-heralder 0.5.0 => 0.5.1
     ```
 
-## Procedure
+    * Read more about the [`uv version`](https://docs.astral.sh/uv/guides/package/#updating-your-version) command.
+
+3. Commit the file changes to `main` and push to GitHub.
 
-1. Bump version number in `herald/__init__.py` and commit to source control.
+4. Build the package:
 
-2. Verify entry in `CHANGELOG.md`.
+    ```bash
+    rm -rf dist/
+    uv build --no-sources
+    ```
 
-3. Build distribution:
-     
-     ```bash
-     python setup.py sdist bdist_wheel
-     ```
+    * Use `--no-sources` when building to publish per [recommendatation from UV](https://docs.astral.sh/uv/guides/publish/#building-your-package)
 
-4. Upload the distribution to PyPI and follow the prompts to provide the API token:
+5. Publish the package to `pypi` (production), or `testpypi` (test) package repository:
 
     ```bash
-    twine upload dist/*
+    uv publish --index [pypi|testpypi]
     ```
 
-5. Create a new release and tag on GitHub:
+    Follow the prompts for a API username `__token__` and password (API token). You can configure an API token in your PyPI account or Test PyPI account.
+
+6. Create a new release and tag on GitHub:
 
     1. Go to [Draft a new release](https://github.com/peterfarrell/django-heralder/releases/new)
     2. Choose tag. If you have not created a tag yet, you can create one "on publish". Use the format of `vX.X.X`.
     3. Set the release title to the version. Ex: `vX.X.X`
-    5. In the body for the release, copy the bullets of items from the `CHANGELOG.md`.
+    5. In the body for the release, copy the bullets of items from the `CHANGELOG.md`.
+
+
+### Using GithHub Trusted Publisher
+
+TODO: See [#39 - Enhance publishing using GitHub Actions and PyPI Trusted Publishers](https://github.com/peterfarrell/django-heralder/issues/39)

RELEASE.md

@@ -1,6 +1,13 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/herald"]
+
 [project]
 name = "django-heralder"
-version = "0.0.0"
+version = "0.5.1"
 requires-python = ">=3.10,<3.14"
 readme = "README.md"
 license = "MIT"
@@ -16,8 +23,8 @@ dependencies = [
 
 keywords = [
     "django",
-     "notifications",
-     "messaging",
+    "notifications",
+    "messaging",
 ]
 
 classifiers = [
@@ -52,3 +59,24 @@ dev = [
     "mock>=5.2.0",
     "pytz>=2025.2",
 ]
+
+[project.urls]
+Homepage = "https://github.com/peterfarrell/django-heralder"
+Repository = "https://github.com/peterfarrell/django-heralder.git"
+Issues = "https://github.com/peterfarrell/django-heralder/issues"
+Changelog = "https://github.com/peterfarrell/django-heralder/blob/main/CHANGELOG.md"
+
+[tool.uv]
+package = true
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple/"
+publish-url = "https://pypi.org/legacy/"
+explicit = true