django-adr 0.1.0__tar.gz

django_adr-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Validate
+        uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # v2.0.4
+
+  test:
+    name: Test
+    runs-on: ubuntu-24.04
+    needs: [validate]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync --frozen --group test
+
+      - name: Test
+        run: |
+          uv run coverage run manage.py test tests --buffer --durations 10 --noinput --parallel --shuffle --timing
+          uv run coverage combine
+          uv run coverage report
+
+  build:
+    name: Build
+    runs-on: ubuntu-24.04
+    needs: [validate, test]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Build distributions
+        run: |
+          uv build
+          ls dist/
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-24.04
+    needs: [build]
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: release
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Publish to PyPI
+        run: uv publish

django_adr-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Environments
+.venv/
+venv/
+env/
+
+# Unit test / coverage reports
+.coverage*
+.coverages/
+.pytest_cache/
+htmlcov/
+*.cover
+
+# Django
+*.log
+db.sqlite3
+
+# Ruff
+.ruff_cache/
+
+# macOS
+.DS_Store
+
+# IDEs
+.idea/
+.vscode/

django_adr-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,60 @@
+default_language_version:
+  python: python3.12
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ["--maxkb=1024"]
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-yaml
+        args: ["--allow-multiple-documents"]
+      - id: debug-statements
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: fix-byte-order-marker
+      - id: forbid-new-submodules
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.1
+    hooks:
+      - id: gitleaks
+  - repo: https://github.com/adhtruong/mirrors-typos
+    rev: v1.47.0
+    hooks:
+      - id: typos
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.21.2
+    hooks:
+      - id: pyupgrade
+        args: [--py312-plus]
+  - repo: https://github.com/adamchainz/django-upgrade
+    rev: 1.30.0
+    hooks:
+      - id: django-upgrade
+        args: [--target-version, "4.2"]
+  - repo: https://github.com/UnknownPlatypus/djangofmt-pre-commit
+    rev: v0.2.9
+    hooks:
+      - id: djangofmt
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.15
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/tox-dev/pyproject-fmt
+    rev: v2.23.0
+    hooks:
+      - id: pyproject-fmt
+  - repo: https://github.com/pycqa/bandit
+    rev: 1.9.4
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml"]

django_adr-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `ADR` model with auto-assigned sequential `number`, `title`, `status`, `date`, `context`, `decision`, `consequences`, and `superseded_by` self-reference
+- Status lifecycle: `proposed`, `accepted`, `deprecated`, `superseded`, `rejected`
+- `clean()` validation enforcing consistency between `status` and `superseded_by`
+- Markdown rendering for `context`, `decision`, and `consequences` via `mistune`
+- `status` filter on HTML list view (`?status=`)
+- Django admin interface with custom fieldsets
+- Read-only REST API (`djangorestframework`) with `superseded_by` exposed as ADR number
+- Management command `create_adr` with optional `--supersedes` flag for atomic supersession
+- Management command `export_adrs` to export ADRs as Markdown files
+- Internationalization support (i18n) with English translations included
+- GitHub Actions CI: `validate` → `build` on every push; `publish` to PyPI on `v*` tags via OIDC Trusted Publisher
+- `uv` for dependency management and task running
+- `Makefile` targets: `help`, `install`, `messages`, `migrate`, `migrations`, `showoutdated`, `test`, `update`, `validate`
+- Pre-commit hooks: `ruff`, `ruff-format`, `pyupgrade`, `django-upgrade`, `djangofmt`, `pyproject-fmt`, `bandit`, `gitleaks`, `typos`

django_adr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niccolò Mineo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_adr-0.1.0/Makefile

@@ -0,0 +1,46 @@
+.DEFAULT_GOAL := help
+
+.PHONY: install
+install:  ## Install all dev dependencies
+	uv sync --group dev
+
+.PHONY: help
+help:  ## Show this help
+	@echo "[Help] Makefile list commands:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: messages
+messages:  ## Extract and compile i18n translation strings
+	uv run manage.py makemessages --add-location file --ignore .venv --locale en $(ARGS)
+	uv run manage.py compilemessages --ignore .venv $(ARGS)
+
+.PHONY: migrate
+migrate:  ## Apply database migrations
+	uv run manage.py migrate --noinput $(ARGS)
+
+.PHONY: migrations
+migrations:  ## Generate new Django migration files
+	uv run manage.py makemigrations --no-header $(ARGS)
+
+.PHONY: showoutdated
+showoutdated:  ## Show outdated dependencies (Python, prek)
+	uv tree --all-groups --outdated | grep --color=always "(latest:.*)" || true
+	uv run prek auto-update --dry-run
+
+.PHONY: test
+test:  ## Run tests with coverage
+	uv run coverage run manage.py test tests --buffer --durations 10 --noinput --parallel --shuffle --timing
+	uv run coverage combine
+	uv run coverage html
+	uv run coverage report
+
+.PHONY: update
+update:  ## Update dependencies, pre-commit hooks and GitHub Actions versions
+	uv lock --upgrade
+	uv sync --group dev
+	uv run prek autoupdate
+	gha-update
+
+.PHONY: validate
+validate:  ## Run pre-commit hooks on all files
+	uv run prek run --all-files

django_adr-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: django-adr
+Version: 0.1.0
+Summary: A Django reusable package to manage Architectural Decision Records.
+Project-URL: homepage, https://niccolomineo.com
+Author: Niccolò Mineo
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+Requires-Dist: django>=4.2
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: mistune>=3
+Description-Content-Type: text/markdown
+
+# django-adr
+
+A Django reusable package to manage **[Architectural Decision Records (ADR)](https://niccolomineo.com/articles/django-architectural-decisions/)**.
+
+> **Warning:** This package is not production ready. APIs and data models may change between versions.
+
+## Features
+
+- Django Admin interface to create and manage ADRs
+- HTML list and detail views with status filtering
+- Read-only REST API (Django REST Framework) with pre-rendered Markdown HTML fields
+- Management command `create_adr` to create ADRs from the CLI, with optional `--supersedes` to mark an existing ADR as superseded in one step
+- Management command `export_adrs` to export all ADRs as Markdown files
+- Markdown support for context, decision, and consequences fields
+- Internationalization (i18n) support — English locale included
+
+## Installation
+
+```bash
+pip install django-adr
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django_adr",
+]
+```
+
+Include the URLs:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    ...
+    path("adrs/", include("django_adr.urls", namespace="django_adr")),
+]
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+## Usage
+
+### Admin
+
+Visit `/admin/django_adr/adr/` to manage ADRs through the Django admin.
+
+### HTML views
+
+- `/adrs/` — list all ADRs
+- `/adrs/?status=accepted` — filter by status
+- `/adrs/<number>/` — view a single ADR
+
+### REST API
+
+- `GET /adrs/api/adrs/` — list all ADRs
+- `GET /adrs/api/adrs/<number>/` — retrieve a single ADR
+
+### Management commands
+
+Create a new ADR:
+
+```bash
+python manage.py create_adr "Use PostgreSQL" \
+    --context="We need a relational database." \
+    --decision="Use PostgreSQL." \
+    --consequences="Team must know SQL."
+```
+
+Create a new ADR and supersede an existing one in a single step:
+
+```bash
+python manage.py create_adr "Use CockroachDB" --supersedes=3
+```
+
+This creates the new ADR and automatically marks ADR-0003 as `Superseded`.
+
+Export all ADRs as Markdown files:
+
+```bash
+python manage.py export_adrs --output-dir=docs/adr
+```
+
+Each ADR is written to `<output-dir>/<number>-<slug>.md`.
+
+## ADR statuses
+
+| Status | Description |
+|--------|-------------|
+| `proposed` | Under discussion |
+| `accepted` | Agreed and in effect |
+| `deprecated` | No longer relevant |
+| `superseded` | Replaced by a newer ADR |
+| `rejected` | Considered and not adopted |
+
+## Protecting the views
+
+The HTML views and REST API are public by default. The package does not enforce any authentication strategy — that is left to the host project.
+
+**HTML views** — in `urls.py`, wrap the URL include with `login_required`:
+
+```python
+from django.contrib.auth.decorators import login_required
+from django.urls import include, path
+
+urlpatterns = [
+    path("adrs/", login_required(include("django_adr.urls", namespace="django_adr"))),
+]
+```
+
+**REST API** — set `DEFAULT_PERMISSION_CLASSES` in `settings.py`:
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
+}
+```
+
+Or scope it to the ADR router only by subclassing `ADRViewSet`:
+
+```python
+from django_adr.api import ADRViewSet
+from rest_framework.permissions import IsAuthenticated
+
+class ProtectedADRViewSet(ADRViewSet):
+    permission_classes = [IsAuthenticated]
+```
+
+## Translations
+
+All user-facing strings are translatable. The package ships with an English locale. To generate translations for your project:
+
+```bash
+python manage.py makemessages -l it
+```
+
+Ensure `USE_I18N = True` in your project settings.
+
+## License
+
+MIT

django_adr-0.1.0/README.md

@@ -0,0 +1,148 @@
+# django-adr
+
+A Django reusable package to manage **[Architectural Decision Records (ADR)](https://niccolomineo.com/articles/django-architectural-decisions/)**.
+
+> **Warning:** This package is not production ready. APIs and data models may change between versions.
+
+## Features
+
+- Django Admin interface to create and manage ADRs
+- HTML list and detail views with status filtering
+- Read-only REST API (Django REST Framework) with pre-rendered Markdown HTML fields
+- Management command `create_adr` to create ADRs from the CLI, with optional `--supersedes` to mark an existing ADR as superseded in one step
+- Management command `export_adrs` to export all ADRs as Markdown files
+- Markdown support for context, decision, and consequences fields
+- Internationalization (i18n) support — English locale included
+
+## Installation
+
+```bash
+pip install django-adr
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django_adr",
+]
+```
+
+Include the URLs:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    ...
+    path("adrs/", include("django_adr.urls", namespace="django_adr")),
+]
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+## Usage
+
+### Admin
+
+Visit `/admin/django_adr/adr/` to manage ADRs through the Django admin.
+
+### HTML views
+
+- `/adrs/` — list all ADRs
+- `/adrs/?status=accepted` — filter by status
+- `/adrs/<number>/` — view a single ADR
+
+### REST API
+
+- `GET /adrs/api/adrs/` — list all ADRs
+- `GET /adrs/api/adrs/<number>/` — retrieve a single ADR
+
+### Management commands
+
+Create a new ADR:
+
+```bash
+python manage.py create_adr "Use PostgreSQL" \
+    --context="We need a relational database." \
+    --decision="Use PostgreSQL." \
+    --consequences="Team must know SQL."
+```
+
+Create a new ADR and supersede an existing one in a single step:
+
+```bash
+python manage.py create_adr "Use CockroachDB" --supersedes=3
+```
+
+This creates the new ADR and automatically marks ADR-0003 as `Superseded`.
+
+Export all ADRs as Markdown files:
+
+```bash
+python manage.py export_adrs --output-dir=docs/adr
+```
+
+Each ADR is written to `<output-dir>/<number>-<slug>.md`.
+
+## ADR statuses
+
+| Status | Description |
+|--------|-------------|
+| `proposed` | Under discussion |
+| `accepted` | Agreed and in effect |
+| `deprecated` | No longer relevant |
+| `superseded` | Replaced by a newer ADR |
+| `rejected` | Considered and not adopted |
+
+## Protecting the views
+
+The HTML views and REST API are public by default. The package does not enforce any authentication strategy — that is left to the host project.
+
+**HTML views** — in `urls.py`, wrap the URL include with `login_required`:
+
+```python
+from django.contrib.auth.decorators import login_required
+from django.urls import include, path
+
+urlpatterns = [
+    path("adrs/", login_required(include("django_adr.urls", namespace="django_adr"))),
+]
+```
+
+**REST API** — set `DEFAULT_PERMISSION_CLASSES` in `settings.py`:
+
+```python
+REST_FRAMEWORK = {
+    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
+}
+```
+
+Or scope it to the ADR router only by subclassing `ADRViewSet`:
+
+```python
+from django_adr.api import ADRViewSet
+from rest_framework.permissions import IsAuthenticated
+
+class ProtectedADRViewSet(ADRViewSet):
+    permission_classes = [IsAuthenticated]
+```
+
+## Translations
+
+All user-facing strings are translatable. The package ships with an English locale. To generate translations for your project:
+
+```bash
+python manage.py makemessages -l it
+```
+
+Ensure `USE_I18N = True` in your project settings.
+
+## License
+
+MIT

django_adr-0.1.0/django_adr/__init__.py

@@ -0,0 +1 @@
+"""Django ADR — a package to manage Architectural Decision Records."""

django_adr-0.1.0/django_adr/admin.py

@@ -0,0 +1,22 @@
+"""Django admin configuration for ADRs."""
+
+from django.contrib import admin
+from django.utils.translation import gettext_lazy as _
+
+from django_adr.models import ADR
+
+
+@admin.register(ADR)
+class ADRAdmin(admin.ModelAdmin):
+    """Admin interface for ADR."""
+
+    list_display = ("number", "title", "status", "date")
+    list_filter = ("status",)
+    search_fields = ("title", "context", "decision", "consequences")
+    readonly_fields = ("number", "date")
+    fieldsets = (
+        (None, {"fields": ("number", "title", "status", "date", "superseded_by")}),
+        (_("Context"), {"fields": ("context",)}),
+        (_("Decision"), {"fields": ("decision",)}),
+        (_("Consequences"), {"fields": ("consequences",)}),
+    )

django_adr-0.1.0/django_adr/api.py

@@ -0,0 +1,14 @@
+"""DRF ViewSets for ADRs."""
+
+from rest_framework.viewsets import ReadOnlyModelViewSet
+
+from django_adr.models import ADR
+from django_adr.serializers import ADRSerializer
+
+
+class ADRViewSet(ReadOnlyModelViewSet):
+    """Provide read-only API access to ADRs."""
+
+    queryset = ADR.objects.select_related("superseded_by").all()
+    serializer_class = ADRSerializer
+    lookup_field = "number"

django_adr-0.1.0/django_adr/apps.py

@@ -0,0 +1,11 @@
+"""Django ADR application configuration."""
+
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+
+
+class DjangoAdrConfig(AppConfig):
+    """Django ADR application configuration."""
+
+    name = "django_adr"
+    verbose_name = _("Architectural Decision Records")