django-i3version 0.0.1

Reusable Django app to track release versions and notify users when a new version is published.

django-i3version

Reusable Django app to track release versions / changelogs of an application, notify users when a new version is published, and (in a future version) accept release publications via API key.

pip install django-i3version

---

Quick start

1. Install + add to INSTALLED_APPS

INSTALLED_APPS = [
    ...,
    "simple_history",      # required dependency, used for history tracking
    "django_i3version",
]

Note on app label. The package module is django_i3version but the Django app label is intentionally set to i3version, so DB tables stay as i3version_*. This makes it possible to drop in this package as a replacement for a project that previously had a local i3version/ Django app — no DB rename, no --fake-initial, no FK-string rewrite.

2. Include URLs (optional)

# urls.py
from django.urls import path, include

urlpatterns = [
    ...,
    path("api/i3version/", include("django_i3version.urls")),
]

This exposes UserVersionViewSet (read-only list / retrieve / mark-as-read) filtered to the authenticated user's notifications and the project's TIER setting (if any).

3. Run migrations

python manage.py migrate i3version

---

Models

• Version — a release row. Fields: numeric_version, str_version, uuid_version, name, tier (local/stage/prod), short_description, description, markdown, microservice_commits (JSON), and the user-group filters user_group_filter / user_group_exclude used at creation time to fan out VersionUserNotified rows.
• VersionAttachment — files attached to a version.
• VersionUserNotified — per-user notification record (is_notified, is_read). Created automatically on Version.save() for every user matching the version's filter. Marked read via the API.

Settings

Setting	Type	Default	Effect
TIER	str	None	If set, the user-version viewset filters only versions of this tier.

Views

• GET /<your-prefix>/ — paginated list of versions visible to the user
• GET /<your-prefix>/{id}/ — single version
• POST /<your-prefix>/{id}/mark_as_read/ — mark this version as read
• POST /<your-prefix>/mark_all_as_read/ — mark all versions as read

Roadmap

• API-key publish endpoint (issue release rows from CI / external systems) via a VersionPublisher model with hashed key.
• Webhooks on new release.
• Pluggable notification backends (Slack, email, Pub/Sub).

Development

make virtualenv_create
source venv/bin/activate
make install_dev
make test           # runs unit tests against in-memory sqlite
make package_build  # build sdist + wheel
make package_upload # twine upload

---

License: GNU GPL v3.0.
Repo: https://github.com/sajlx/django-i3version