Metadata-Version: 2.4
Name: django_i3version
Version: 0.0.1
Summary: Reusable Django app to track release versions and notify users when a new version is published.
Home-page: https://github.com/sajlx/django-i3version
Author: Ivan Bettarini
Author-email: ivan.bettarini@gmail.com
License: GNU General Public License v3.0
Classifier: Environment :: Web Environment
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=4.2
Requires-Dist: djangorestframework>=3.14
Requires-Dist: django-simple-history>=3.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# 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`

```python
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)

```python
# 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
