Django Libraryv0.6.0

🐛issuetracker is the issue-tracking capability your Django app doesn't have to build.

Issue tracking should be composable infrastructure, not application-specific reinvention.

Almost every serious application eventually needs to track bugs, support requests, and internal work — and the model itself is never the hard part. The real cost is identity resolution, permissions, lifecycle, comments, labels, attachments, pagination, filtering, and a versioned API around all of it. Generic Issue Tracker packages that subsystem as an installable Django app: your application keeps owning its product, the tracker owns issue tracking.

Core Resources — Issues, Comments, Labels, Files

Versioned REST API

Hard Dependency on AUTH_USER_MODEL

Soft

Delete by Default

PyPI Package Source Documentation

genericissuetracker

Live

$curl -X POST http://localhost:8000/api/v1/issues/ ...

pip install · no build step · drop into any Python project

What's New

Why It Exists

An Issue model is the easy part — the real work is authentication, identity resolution, permissions, lifecycle, comments, labels, attachments, pagination, filtering, and API versioning, rebuilt slightly differently in every application.
Bolting issue tracking onto an app's existing user model couples two systems that should evolve independently — and breaks the moment that app's identity system changes.
Letting clients set an issue's status directly turns 'authenticated' into 'authorized' by accident — lifecycle rules need to be enforced on the server, not trusted from the request body.

One resource. Two explicit surfaces.

Write API — /api/v1/issues/

Create (open to anonymous, email-gated)
Update & soft delete (authenticated only)
Status transitions — change-status/ — policy-guarded

Read API — /api/v1/issues-read/

List & retrieve only, never mutates
Nested comments, labels, attachments in one response
Search + ordering via standard DRF query params

Same resource, deliberately separated read and write surfaces

What issuetracker Does

Human-Friendly Issue Numbers: Every issue keeps a UUID as its internal, machine-safe identity and a separate sequential issue_number — assigned inside a DB transaction via MAX() aggregation — as its public identity. Machines get UUIDs, people get #143.
Identity Without Owning Your User Model: Reporters and commenters are stored as reporter_email / reporter_user_id, never a ForeignKey to AUTH_USER_MODEL. A pluggable IDENTITY_RESOLVER decides how a request maps to that identity — Django auth, AuthX, SSO, or anonymous with a required email.
Lifecycle-Guarded Status Transitions: Status changes go through a dedicated change-status/ action, not a raw PATCH — an explicit ALLOWED_TRANSITIONS table rejects illegal jumps (OPEN can’t go straight to RESOLVED) and records every change in a timeline-ready IssueStatusHistory event.
Soft Delete Is the Default, Not an Add-on: Every model inherits a base with is_deleted / deleted_at and a manager that filters them out automatically — deleting an issue never breaks the comments, attachments, or history that reference it.
Anti-Spoofing Built Into the Serializer Layer: reporter_user_id, reporter_email, and comment identity fields are popped from client input before validation and re-injected from the resolved identity — a request can’t claim to be someone else’s issue or comment.
Versioned From Day One: Every endpoint lives under /api/v1/, with models, services, serializers, and views kept in explicit layers — and drf-spectacular wired in for an OpenAPI schema that stays in sync with the real contract.

DjangoDjango REST FrameworkIssue TrackerVersioned API

Install & Quickstart

Install

pip install genericissuetracker

Create an issue (anonymous reporting allowed)

POST /api/v1/issues/
content-type: application/json

{ "title": "...", "description": "...", "reporter_email": "you@example.com" }

Search and order issues

GET /api/v1/issues/?search=checkout&ordering=-created_at

Comment on an issue (by issue_number, not UUID)

POST /api/v1/comments/
Authorization: Bearer <token>

{ "issue": 143, "body": "..." }

Move an issue through its lifecycle

POST /api/v1/issues/143/change-status/

{ "status": "IN_PROGRESS" }

Security & Trust Boundaries

reporter_user_id and reporter_email are stripped from client input and re-injected from the resolved server-side identity — a request body can never spoof who reported or commented on an issue.
Status transitions are validated against an explicit allow-list on the server; a client can request a transition, but only a legal one is ever applied.
Soft delete keeps historical data — comments, attachments, audit trail — intact and queryable via all_objects, while the default manager keeps deleted records out of every normal query.
The API ships permissive by default (AllowAny) so it's usable out of the box — DEFAULT_PERMISSION_CLASSES is a host-project setting specifically so production deployments are expected to tighten it.
Create is open to anonymous callers only when ALLOW_ANONYMOUS_REPORTING is on, and even then a reporter_email is mandatory — update and delete always require an authenticated identity.

Don't build an issue tracker inside every application.

Install the capability.

Projects · Issues · Comments · Labels · Attachments — one versioned API

Install issuetracker View Source