Visit djangoplay.org ↗
issuetracker
DocsGeneric Issue Tracker

Generic Issue Tracker

A production-grade, reusable, installable Django issue tracking library — versioned, schema-safe, soft-delete-compatible, built to integrate into any Django application.

Install Generic Issue TrackerChangelogUser guide
Latest v0.6.0Updated Oct 1, 202628 pages
bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Start here

The shortest path from nothing to your first result.

  1. 11 min readInstallationUse the repository's declared dependency and bootstrap mechanism.
  2. 21 min readConfigurationKeep environment-specific values outside committed source code.
  3. 31 min readPermissionsPermissions should be evaluated from the authenticated identity and project membership.

Browse by topic

Grouped the same way as the sidebar.

User guide6

API3

Architecture6

Assets1

Changelog1

Deployment3

Runbooks5

Works with

Projects that Generic Issue Tracker declares a relationship with in project.json.

djangoplay-webModular, enterprise-grade Django/DRF backend platform for internal organizational systems — identity, permissions, auditability, and correctness as first-class concerns.authx-identityA standalone OpenID Connect (OIDC) identity microservice, built with FastAPI, plus a small Django client for services that need to talk to it.
Full project README

Python PyPI Downloads Build License GitHub Release GitHub Stars

🚀 Overview

It provides:

  • Issue management
  • Comments
  • Labels
  • Attachments
  • Human-friendly issue numbers
  • Versioned REST API
  • Configurable permissions
  • Configurable pagination
  • Configurable filtering
  • OpenAPI schema support (drf-spectacular compatible)

Designed for:

  • SaaS platforms
  • Internal tools
  • Public open-source issue hubs
  • Enterprise-grade Django systems

🏗 Architecture

Layered Design

plaintext
Models (Domain)
    ↓
Services (Identity / Permissions / Pagination / Filtering)
    ↓
Serializers (Validation & Representation)
    ↓
Versioned Views
    ↓
Versioned URLs
    ↓
OpenAPI Schema

Design Principles

  • No dependency on AUTH_USER_MODEL
  • Soft delete first-class
  • UUID internal identity
  • Sequential issue_number public identity
  • Strict versioning (/api/v1/)
  • Deterministic schema
  • Zero business logic in views
  • Fat serializers, thin views
  • No runtime schema mutation

📦 Installation

bash
pip install genericissuetracker

Add to INSTALLED_APPS:

python
INSTALLED_APPS = [
    ...
    "genericissuetracker",
]

Include URLs:

python
path("api/", include("genericissuetracker.urls.root")),

🛠 Required Dependencies

  • Django >= 4.2
  • djangorestframework >= 3.14
  • drf-spectacular >= 0.27

⚙ Configuration

All settings are namespaced:

python
GENERIC_ISSUETRACKER_<SETTING>

Available Settings

Setting Description
IDENTITY_RESOLVER Custom identity resolver path
ALLOW_ANONYMOUS_REPORTING Allow anonymous issue creation
MAX_ATTACHMENTS Max attachments per issue
MAX_ATTACHMENT_SIZE_MB Max file size
DEFAULT_PERMISSION_CLASSES Default DRF permissions
DEFAULT_PAGINATION_CLASS Pagination class
PAGE_SIZE Pagination size
DEFAULT_FILTER_BACKENDS Filtering backends

Example:

python
GENERIC_ISSUETRACKER_DEFAULT_PERMISSION_CLASSES = [
    "rest_framework.permissions.IsAuthenticated"
]

🔐 Identity Model

Reporter is stored as:

  • reporter_email
  • reporter_user_id (optional)

No direct ForeignKey to user model.

🧾 Issue Identifiers

  • id → UUID (internal)
  • issue_number → Sequential public identifier

Example:

plaintext
/api/v1/issues/12/

📚 API Endpoints

Issues

Method Endpoint
GET /api/v1/issues/
GET /api/v1/issues/{issue_number}/
POST /api/v1/issues/
PUT /api/v1/issues/{issue_number}/
PATCH /api/v1/issues/{issue_number}/
DELETE /api/v1/issues/{issue_number}/

Comments

plaintext
/api/v1/comments/

Labels

plaintext
/api/v1/labels/

Attachments

plaintext
/api/v1/attachments/

🔎 Filtering

Supports:

  • SearchFilter
  • OrderingFilter

Example:

plaintext
/api/v1/issues/?search=bug
/api/v1/issues/?ordering=-created_at

📄 Pagination

Configurable via:

plaintext
GENERIC_ISSUETRACKER_PAGE_SIZE

📖 OpenAPI Schema

Fully compatible with drf-spectacular.

plaintext
/schema/
/docs/

🧪 Development

Install dev tools:

bash
pip install -e ".[dev]"
ruff check .

🧩 Integration Guide

  1. Install package
  2. Add to INSTALLED_APPS
  3. Include URLs
  4. Configure permissions
  5. Run migrations
  6. Start creating issues

🧱 Versioning Policy

  • Minor releases: new features (backward compatible)
  • Patch releases: internal improvements
  • Major releases: breaking changes

📜 License

MIT License.

👤 Maintainer

BinaryFleet

🌟 Contributing

Pull requests welcome. Follow:

  • DRY principles
  • Schema determinism
  • Versioned serializers
  • No business logic in views

License

Licensed under the Apache License.

See the LICENSE and NOTICE file for details.