django-dg-board 1.0.0__tar.gz

django_dg_board-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+.env
+*.sqlite3
+.DS_Store
+
+# The example project
+example/db.sqlite3
+example/media/
+
+# Jasper's own instructions for agents
+CLAUDE.local.md

django_dg_board-1.0.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog of django-dg-board
+
+## 1.0.0 (2026-11-07)
+
+The first release: the kanban board with groups and their own columns, tickets with parents, relations,
+blockers, labels, sizes, comments and attachments, @-mentions and watchers, the activity feed, links to
+GitHub code, what names a ticket in the other DataGroceries apps (such as wiki pages), a REST API and MCP tools
+for working on tickets as on the pages, and English and Dutch. It started as Eddy Board, Eddy Grid's own
+tracker.

django_dg_board-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jasper Cramwinckel
+
+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_dg_board-1.0.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.5
+Name: django-dg-board
+Version: 1.0.0
+Summary: A kanban ticket tracker for Django that people and AI agents work on together.
+Project-URL: Homepage, https://github.com/datagroceries/django-dg
+Project-URL: Source, https://github.com/datagroceries/django-dg
+Project-URL: Documentation, https://github.com/datagroceries/django-dg/blob/main/docs/integrating.md
+Project-URL: Changelog, https://github.com/datagroceries/django-dg/blob/main/packages/django-dg-board/CHANGELOG.md
+Author: Jasper Cramwinckel
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai agents,django,issue tracker,kanban,mcp,ticket tracker
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Office/Business :: Groupware
+Classifier: Topic :: Software Development :: Bug Tracking
+Requires-Python: >=3.11
+Requires-Dist: django-dg-core>=1.0
+Requires-Dist: django-simple-history
+Requires-Dist: django>=5.2
+Requires-Dist: markdown
+Requires-Dist: requests
+Description-Content-Type: text/markdown
+
+# django-dg-board
+
+A kanban ticket tracker for a Django project, that people and AI agents work on together. Part of
+[DataGroceries](https://github.com/datagroceries/django-dg). It started as Eddy Board, the tracker
+[Eddy Grid](https://eddygrid.com) built for its own team, which kindly agreed to its release, and keeps its
+design.
+
+## What it does
+
+- A kanban board with drag and drop, groups per team or project with their own columns, and filters on
+  assignee, creator, label, text, and a ticket with everything under it.
+- Tickets with a Markdown description, labels, a size, comments with one level of replies, and
+  attachments dropped or pasted onto the page; parents and subtasks, blockers, duplicates and related
+  tickets.
+- Every change kept, with who made it and through which agent, shown per ticket as one activity feed.
+- @-mentions and watchers, told by email or Slack.
+- Links to the GitHub commits, branches and pull requests that mention a ticket.
+- A REST API and MCP tools, so an agent works on tickets as the person who connected it.
+- English and Dutch, following the project's language.
+
+How the board is built, its requirements and its principles are in
+[docs/board.md](https://github.com/datagroceries/django-dg/blob/main/docs/board.md).
+
+## Installing
+
+The full guide, for a project that already has its own logins, users, API tokens or front end, is
+[docs/integrating.md](https://github.com/datagroceries/django-dg/blob/main/docs/integrating.md). In short:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'django.contrib.humanize',
+    'rest_framework',
+    'simple_history',
+    'datagroceries.core',
+    'datagroceries.board',
+]
+```
+
+```python
+urlpatterns = [
+    ...,
+    path('dg/', include('datagroceries.urls')),  # every DataGroceries app and the MCP endpoint
+]
+```
+
+Then `manage.py migrate`, and `manage.py check`, which says what is still missing, such as who may use
+the board. The pages bring their own layout, `dg_core/base.html`, so they work whatever
+the project's front end is. To show them inside the project's own layout instead, override that template,
+as with Django's admin: it says what it must keep.
+
+Who may use the board is a Django permission, "Can use the board" (`dg_board.use`): grant it to a
+group in the admin, and put people in that group. Superusers have it. Those who have it are the board's
+people: they can be assigned and @-mentioned. Each one's @-handle is their username by default. A
+project that sees its people differently, such as by a nickname, a photo or rules of its own, names a
+subclass of `datagroceries.core.people.People` in `DG_PEOPLE`; that module says how.
+
+**Settings.** `DG_BOARD_NAME`, `DG_BOARD_KEY_PREFIX`, `DG_BOARD_DISPLAY_TIMEZONE` and
+`DG_BOARD_COLORS`, each with a default (`conf.py`), and the GitHub settings below. Avatars are an
+image when the project's `People` gives one, and initials otherwise (`datagroceries.core.people`).
+
+**Languages.** English and Dutch, following the project's language (`django.utils.translation`); the
+JavaScript's texts through Django's JavaScript catalog (`dg/jsi18n/`). The API and the MCP tools stay
+English.
+
+**Front end.** Bootstrap 5.3.8, Bootstrap Icons 1.13.1 and the Markdown editor (EasyMDE 2.21.0)
+from core, plus htmx 1.9.8, SortableJS 1.15.7 (drag and drop) and Tom Select 2.6.2 (searchable and
+multi-selects). All ship in the packages (`static/*/vendor/`, each with its licence), not from a CDN, so
+the pages work offline, on an internal network and under a strict Content Security Policy, and no third
+party sees who visits them. Form fields get their
+Bootstrap layout from the board's own `field` tag, so the project needs no form package. Markdown is rendered
+by core (`datagroceries.core.markdown`), as in every DataGroceries app; the board adds its ticket keys and @-mentions to it
+(`ticket_links.py`), so they show in the other apps' Markdown too.
+
+## Notifications
+
+- A ticket's `Watcher`s hear about it: comments (with the text quoted), the ticket being blocked or
+  unblocked (with the reason) and its entering a done column. A new assignee and anyone @-mentioned in a
+  comment or the description hear about that too. A message about a comment links straight to it
+  (`#comment-12`), and so does a comment's own 🔗 on the page.
+- Creator, assignee, commenters and @-mentioned people start watching on their own; anyone can switch
+  it on or off on the ticket page.
+- `@jasper` mentions the person whose handle is `jasper`. In every Markdown editor,
+  `@` and the start of a handle, first or last name lists the people it may mean, and a pick fills in
+  the handle that reaches them (core's `editor.js`, from the board's `mention_people` tag); not inside code. While it is
+  written, each `@handle` that reaches someone is marked, so a typo shows before saving.
+- Nobody hears about their own change. Only the views notify (`notifications.py`), never a model
+  signal, so bulk changes stay quiet.
+- A message goes out once the change is committed, through `datagroceries.core.notifications`: by email, or as a
+  Slack direct message, or Slack with email for whoever it cannot reach (`DG_NOTIFICATIONS`).
+
+## API for agents
+
+An agent reads and writes tickets through `dg/board/api/tickets/` as the person it works for, with a
+connected app or a personal token (django-dg-connect, at `dg/connect/`), or through the board's tools on the one MCP endpoint, `dg/mcp`.
+The token goes as `Authorization: Bearer dg_…`, or as `Token dg_…` as with DRF's own tokens. A
+project with ways in of its own (its own tokens, JWT, anything DRF can check) lists their classes in
+`DG_AUTHENTICATION_CLASSES`, so its people need no second token; a key without the `dg_` prefix is
+left to them. A project with its own OAuth server names it in `DG_AUTHORIZATION_SERVER`, and the MCP
+endpoint's 401 then points MCP clients there (`datagroceries.core.authentication`). The views are in `api.py` and
+the tools, which run those views, in `mcp.py`.
+
+- Whatever lets a request in, it reaches the board's area (`board`) only while its person may use the
+  board, and only if the token's scopes, when it has them, cover it. Checked on every request.
+- People are named by their handle, with their email address beside it when they have one; an assignee
+  may be given as either.
+- Changes go through `operations.py` and the pages' forms, notifications included. Their history
+  records carry `via <token name>`, `via <OAuth app>` or `via API` as change reason, which the activity
+  feed shows.
+- Editing a comment works as on the page: only its author may, and only people it newly @-mentions
+  hear about it.
+- Not in the API: deleting tickets or groups, uploading attachments, and making groups and columns.
+
+## GitHub
+
+Code in the repository (`DG_BOARD_GITHUB_REPOSITORY`) that mentions a ticket's key is linked to it, as a
+`CodeReference`, and listed in a Code panel on the ticket page (pull requests first, then branches, then
+commits) and under `code` in the ticket API. `github.py` does the work:
+
+- **Commits** on the default branch count by the keys in their message, which on `main` is the squashed
+  pull request.
+- **Branches** count by the keys in their name, in any case (`anna/t-123-invoices`). A branch stands
+  in for its work until a pull request is opened from it, which then replaces it on the ticket, so
+  merged-and-deleted branches do not pile up.
+- **Pull requests** count by the keys in their title and their branch's name, not their description,
+  which names other tickets in passing. The state follows the pull request (open, merged, closed, in
+  the colours of the column categories), and a key taken out of the title takes its link away.
+- A key that names no ticket is ignored.
+- **Deliberately not:** a merged pull request does not move its ticket to done. The link and its state
+  show on the ticket; moving it stays with people.
+
+**The webhook** at `dg/board/github/webhook/` takes GitHub's `push`, `pull_request` and `create` events.
+It needs no login, and proves the sender by the `X-Hub-Signature-256` signature instead, made with
+`DG_BOARD_GITHUB_WEBHOOK_SECRET`. Other repositories, pushes to other branches, tags and other events
+link nothing.
+
+**The backfill**, `manage.py backfill_github [--since 2025-03-01]`, reads the default branch's commits
+and every pull request from the GitHub API with `DG_BOARD_GITHUB_TOKEN`, 100 a request, and is safe to run
+again. Branches are left to the webhook: GitHub keeps no record of who made one when, and a branch that
+got a pull request is represented by it anyway.
+
+**Setting it up**, once:
+
+1. `DG_BOARD_GITHUB_REPOSITORY` (`owner/name`), a fine-grained GitHub token for the repository with
+   read-only Contents, Pull requests and Metadata as `DG_BOARD_GITHUB_TOKEN`, and a long random
+   `DG_BOARD_GITHUB_WEBHOOK_SECRET`. While the secret is empty the webhook refuses every delivery,
+   and without the token the backfill stops.
+2. A webhook in the repository's settings: payload URL `https://<your site>/dg/board/github/webhook/`,
+   content type `application/json`, the same secret, and the individual events Pushes, Pull requests
+   and Branch or tag creation. GitHub's first delivery is a ping, which should answer 200.
+3. `manage.py backfill_github`.

django_dg_board-1.0.0/README.md

@@ -0,0 +1,151 @@
+# django-dg-board
+
+A kanban ticket tracker for a Django project, that people and AI agents work on together. Part of
+[DataGroceries](https://github.com/datagroceries/django-dg). It started as Eddy Board, the tracker
+[Eddy Grid](https://eddygrid.com) built for its own team, which kindly agreed to its release, and keeps its
+design.
+
+## What it does
+
+- A kanban board with drag and drop, groups per team or project with their own columns, and filters on
+  assignee, creator, label, text, and a ticket with everything under it.
+- Tickets with a Markdown description, labels, a size, comments with one level of replies, and
+  attachments dropped or pasted onto the page; parents and subtasks, blockers, duplicates and related
+  tickets.
+- Every change kept, with who made it and through which agent, shown per ticket as one activity feed.
+- @-mentions and watchers, told by email or Slack.
+- Links to the GitHub commits, branches and pull requests that mention a ticket.
+- A REST API and MCP tools, so an agent works on tickets as the person who connected it.
+- English and Dutch, following the project's language.
+
+How the board is built, its requirements and its principles are in
+[docs/board.md](https://github.com/datagroceries/django-dg/blob/main/docs/board.md).
+
+## Installing
+
+The full guide, for a project that already has its own logins, users, API tokens or front end, is
+[docs/integrating.md](https://github.com/datagroceries/django-dg/blob/main/docs/integrating.md). In short:
+
+```python
+INSTALLED_APPS = [
+    ...,
+    'django.contrib.humanize',
+    'rest_framework',
+    'simple_history',
+    'datagroceries.core',
+    'datagroceries.board',
+]
+```
+
+```python
+urlpatterns = [
+    ...,
+    path('dg/', include('datagroceries.urls')),  # every DataGroceries app and the MCP endpoint
+]
+```
+
+Then `manage.py migrate`, and `manage.py check`, which says what is still missing, such as who may use
+the board. The pages bring their own layout, `dg_core/base.html`, so they work whatever
+the project's front end is. To show them inside the project's own layout instead, override that template,
+as with Django's admin: it says what it must keep.
+
+Who may use the board is a Django permission, "Can use the board" (`dg_board.use`): grant it to a
+group in the admin, and put people in that group. Superusers have it. Those who have it are the board's
+people: they can be assigned and @-mentioned. Each one's @-handle is their username by default. A
+project that sees its people differently, such as by a nickname, a photo or rules of its own, names a
+subclass of `datagroceries.core.people.People` in `DG_PEOPLE`; that module says how.
+
+**Settings.** `DG_BOARD_NAME`, `DG_BOARD_KEY_PREFIX`, `DG_BOARD_DISPLAY_TIMEZONE` and
+`DG_BOARD_COLORS`, each with a default (`conf.py`), and the GitHub settings below. Avatars are an
+image when the project's `People` gives one, and initials otherwise (`datagroceries.core.people`).
+
+**Languages.** English and Dutch, following the project's language (`django.utils.translation`); the
+JavaScript's texts through Django's JavaScript catalog (`dg/jsi18n/`). The API and the MCP tools stay
+English.
+
+**Front end.** Bootstrap 5.3.8, Bootstrap Icons 1.13.1 and the Markdown editor (EasyMDE 2.21.0)
+from core, plus htmx 1.9.8, SortableJS 1.15.7 (drag and drop) and Tom Select 2.6.2 (searchable and
+multi-selects). All ship in the packages (`static/*/vendor/`, each with its licence), not from a CDN, so
+the pages work offline, on an internal network and under a strict Content Security Policy, and no third
+party sees who visits them. Form fields get their
+Bootstrap layout from the board's own `field` tag, so the project needs no form package. Markdown is rendered
+by core (`datagroceries.core.markdown`), as in every DataGroceries app; the board adds its ticket keys and @-mentions to it
+(`ticket_links.py`), so they show in the other apps' Markdown too.
+
+## Notifications
+
+- A ticket's `Watcher`s hear about it: comments (with the text quoted), the ticket being blocked or
+  unblocked (with the reason) and its entering a done column. A new assignee and anyone @-mentioned in a
+  comment or the description hear about that too. A message about a comment links straight to it
+  (`#comment-12`), and so does a comment's own 🔗 on the page.
+- Creator, assignee, commenters and @-mentioned people start watching on their own; anyone can switch
+  it on or off on the ticket page.
+- `@jasper` mentions the person whose handle is `jasper`. In every Markdown editor,
+  `@` and the start of a handle, first or last name lists the people it may mean, and a pick fills in
+  the handle that reaches them (core's `editor.js`, from the board's `mention_people` tag); not inside code. While it is
+  written, each `@handle` that reaches someone is marked, so a typo shows before saving.
+- Nobody hears about their own change. Only the views notify (`notifications.py`), never a model
+  signal, so bulk changes stay quiet.
+- A message goes out once the change is committed, through `datagroceries.core.notifications`: by email, or as a
+  Slack direct message, or Slack with email for whoever it cannot reach (`DG_NOTIFICATIONS`).
+
+## API for agents
+
+An agent reads and writes tickets through `dg/board/api/tickets/` as the person it works for, with a
+connected app or a personal token (django-dg-connect, at `dg/connect/`), or through the board's tools on the one MCP endpoint, `dg/mcp`.
+The token goes as `Authorization: Bearer dg_…`, or as `Token dg_…` as with DRF's own tokens. A
+project with ways in of its own (its own tokens, JWT, anything DRF can check) lists their classes in
+`DG_AUTHENTICATION_CLASSES`, so its people need no second token; a key without the `dg_` prefix is
+left to them. A project with its own OAuth server names it in `DG_AUTHORIZATION_SERVER`, and the MCP
+endpoint's 401 then points MCP clients there (`datagroceries.core.authentication`). The views are in `api.py` and
+the tools, which run those views, in `mcp.py`.
+
+- Whatever lets a request in, it reaches the board's area (`board`) only while its person may use the
+  board, and only if the token's scopes, when it has them, cover it. Checked on every request.
+- People are named by their handle, with their email address beside it when they have one; an assignee
+  may be given as either.
+- Changes go through `operations.py` and the pages' forms, notifications included. Their history
+  records carry `via <token name>`, `via <OAuth app>` or `via API` as change reason, which the activity
+  feed shows.
+- Editing a comment works as on the page: only its author may, and only people it newly @-mentions
+  hear about it.
+- Not in the API: deleting tickets or groups, uploading attachments, and making groups and columns.
+
+## GitHub
+
+Code in the repository (`DG_BOARD_GITHUB_REPOSITORY`) that mentions a ticket's key is linked to it, as a
+`CodeReference`, and listed in a Code panel on the ticket page (pull requests first, then branches, then
+commits) and under `code` in the ticket API. `github.py` does the work:
+
+- **Commits** on the default branch count by the keys in their message, which on `main` is the squashed
+  pull request.
+- **Branches** count by the keys in their name, in any case (`anna/t-123-invoices`). A branch stands
+  in for its work until a pull request is opened from it, which then replaces it on the ticket, so
+  merged-and-deleted branches do not pile up.
+- **Pull requests** count by the keys in their title and their branch's name, not their description,
+  which names other tickets in passing. The state follows the pull request (open, merged, closed, in
+  the colours of the column categories), and a key taken out of the title takes its link away.
+- A key that names no ticket is ignored.
+- **Deliberately not:** a merged pull request does not move its ticket to done. The link and its state
+  show on the ticket; moving it stays with people.
+
+**The webhook** at `dg/board/github/webhook/` takes GitHub's `push`, `pull_request` and `create` events.
+It needs no login, and proves the sender by the `X-Hub-Signature-256` signature instead, made with
+`DG_BOARD_GITHUB_WEBHOOK_SECRET`. Other repositories, pushes to other branches, tags and other events
+link nothing.
+
+**The backfill**, `manage.py backfill_github [--since 2025-03-01]`, reads the default branch's commits
+and every pull request from the GitHub API with `DG_BOARD_GITHUB_TOKEN`, 100 a request, and is safe to run
+again. Branches are left to the webhook: GitHub keeps no record of who made one when, and a branch that
+got a pull request is represented by it anyway.
+
+**Setting it up**, once:
+
+1. `DG_BOARD_GITHUB_REPOSITORY` (`owner/name`), a fine-grained GitHub token for the repository with
+   read-only Contents, Pull requests and Metadata as `DG_BOARD_GITHUB_TOKEN`, and a long random
+   `DG_BOARD_GITHUB_WEBHOOK_SECRET`. While the secret is empty the webhook refuses every delivery,
+   and without the token the backfill stops.
+2. A webhook in the repository's settings: payload URL `https://<your site>/dg/board/github/webhook/`,
+   content type `application/json`, the same secret, and the individual events Pushes, Pull requests
+   and Branch or tag creation. GitHub's first delivery is a ping, which should answer 200.
+3. `manage.py backfill_github`.

django_dg_board-1.0.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "django-dg-board"
+version = "1.0.0"
+description = "A kanban ticket tracker for Django that people and AI agents work on together."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Jasper Cramwinckel" }]
+keywords = ["django", "kanban", "ticket tracker", "issue tracker", "mcp", "ai agents"]
+dependencies = [
+    "django-dg-core>=1.0",
+    "Django>=5.2",
+    "django-simple-history",
+    "markdown",
+    "requests",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Bug Tracking",
+    "Topic :: Office/Business :: Groupware",
+]
+
+[project.urls]
+Homepage = "https://github.com/datagroceries/django-dg"
+Source = "https://github.com/datagroceries/django-dg"
+Documentation = "https://github.com/datagroceries/django-dg/blob/main/docs/integrating.md"
+Changelog = "https://github.com/datagroceries/django-dg/blob/main/packages/django-dg-board/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/datagroceries"]

django_dg_board-1.0.0/src/datagroceries/board/activity.py

@@ -0,0 +1,174 @@
+"""The activity feed on a ticket page: field changes, relation changes and comments, newest first."""
+
+import dataclasses
+import datetime
+
+from django.db.models import Prefetch, Q
+from django.utils.translation import gettext as _
+from django.utils.translation import gettext_lazy
+from simple_history.models import DeletedObject
+
+from datagroceries.board.models import Column, Comment, Group, Relation, Ticket
+from datagroceries.core import people
+
+# Fields whose change is not worth a line: bookkeeping, or shown another way (blocked has its comment).
+QUIET_FIELDS = ('closed_at', 'is_blocked')
+# Bootstrap icon for an entry, by the first field it changed.
+FIELD_ICONS = {
+    'title': 'bi-pencil',
+    'description': 'bi-text-left',
+    'column': 'bi-arrow-right-circle',
+    'assignee': 'bi-person',
+    'size': 'bi-hourglass-split',
+    'labels': 'bi-tag',
+}
+
+
+@dataclasses.dataclass
+class Entry:
+    when: datetime.datetime
+    user: object
+    lines: list[str] = dataclasses.field(default_factory=list)
+    comment: Comment | None = None
+    # Who to name when there is no user, e.g. a change written by an import command.
+    fallback: str = gettext_lazy('Someone')
+    icon: str = 'bi-dot'
+    # "via Claude Code on my laptop" when made with an API token.
+    via: str = ''
+
+
+def _via(record) -> str:
+    """The history keeps "via Claude Code on my laptop" in English; it shows in the reader's language."""
+    reason = record.history_change_reason or ''
+    return _('via %(name)s') % {'name': reason.removeprefix('via ')} if reason.startswith('via ') else ''
+
+
+def _person(user) -> str:
+    if isinstance(user, DeletedObject):
+        return _('a deleted user')
+    return people.name(user) if user else _('nobody')
+
+
+def _last_version(model, pk):
+    """The last history record of a row, which outlives the row itself."""
+    return model.history.filter(id=pk).order_by('-history_date', '-history_id').first()
+
+
+def _column_names(column) -> tuple[str, str]:
+    """(group name, column name), also for a column deleted since, from its last history record."""
+    if not isinstance(column, DeletedObject):
+        return column.group.name, column.name
+    record = _last_version(Column, column.pk)
+    group = Group.objects.filter(pk=record.group_id).first() or _last_version(Group, record.group_id)
+    return group.name, record.name
+
+
+def _change_line(field: str, old, new) -> str:
+    # simple_history hands an empty foreign key over as a DeletedObject without a pk.
+    old, new = (None if isinstance(value, DeletedObject) and value.pk is None else value for value in (old, new))
+    if field == 'title':
+        return _('renamed the ticket from "%(old)s" to "%(new)s"') % {'old': old, 'new': new}
+    if field == 'description':
+        return _('edited the description')
+    if field == 'column':
+        (old_group, old_name), (new_group, new_name) = _column_names(old), _column_names(new)
+        if old_group != new_group:
+            return _('moved it from %(old)s to %(new)s') % {
+                'old': f'{old_group} / {old_name}',
+                'new': f'{new_group} / {new_name}',
+            }
+        return _('moved it from %(old)s to %(new)s') % {'old': old_name, 'new': new_name}
+    if field == 'assignee':
+        if not old:
+            return _('assigned it to %(person)s') % {'person': _person(new)}
+        if not new:
+            return _('removed %(person)s as assignee') % {'person': _person(old)}
+        return _('changed the assignee from %(old)s to %(new)s') % {'old': _person(old), 'new': _person(new)}
+    if field == 'size':
+        return _('set the size to %(size)s') % {'size': Ticket.Size(new).label} if new else _('cleared the size')
+    if field == 'labels':
+        # With foreign_keys_are_objs each through row holds the Label itself (or a DeletedObject).
+        old_names = {str(row['label']) for row in old}
+        new_names = {str(row['label']) for row in new}
+        parts = [_('added label "%(name)s"') % {'name': name} for name in sorted(new_names - old_names)]
+        parts += [_('removed label "%(name)s"') % {'name': name} for name in sorted(old_names - new_names)]
+        return ', '.join(parts)
+    return _('changed %(field)s') % {'field': field}
+
+
+def _relation_line(record, ticket: Ticket) -> str:
+    if record.source_id == ticket.pk:
+        relation = f'{Relation.Type(record.type).label} {Ticket(pk=record.target_id).key}'
+    else:
+        relation = f'{Relation.INVERSE_LABELS[record.type]} {Ticket(pk=record.source_id).key}'
+    if record.history_type == '+':
+        return _('added "%(relation)s"') % {'relation': relation}
+    return _('removed "%(relation)s"') % {'relation': relation}
+
+
+def build_feed(ticket: Ticket) -> list[Entry]:
+    entries = []
+    previous = None
+    for record in ticket.history.select_related('history_user').order_by('history_date', 'history_id'):
+        if previous is None:
+            entries.append(
+                Entry(
+                    record.history_date,
+                    record.history_user,
+                    [_('created the ticket')],
+                    icon='bi-plus-circle',
+                    via=_via(record),
+                ),
+            )
+        else:
+            delta = record.diff_against(previous, excluded_fields=QUIET_FIELDS, foreign_keys_are_objs=True)
+            changes = [change for change in delta.changes if _change_line(change.field, change.old, change.new)]
+            if changes:
+                entries.append(
+                    Entry(
+                        record.history_date,
+                        record.history_user,
+                        [_change_line(change.field, change.old, change.new) for change in changes],
+                        fallback=record.history_change_reason or _('Someone'),
+                        icon=FIELD_ICONS.get(changes[0].field, 'bi-dot'),
+                        via=_via(record),
+                    ),
+                )
+        previous = record
+
+    relation_records = Relation.history.filter(Q(source_id=ticket.pk) | Q(target_id=ticket.pk)).exclude(
+        history_type='~',
+    )
+    entries += [
+        Entry(
+            record.history_date,
+            record.history_user,
+            [_relation_line(record, ticket)],
+            fallback=record.history_change_reason or _('Someone'),
+            icon='bi-link-45deg',
+            via=_via(record),
+        )
+        for record in relation_records.select_related('history_user')
+    ]
+
+    comments = (
+        ticket.comments.filter(parent=None)
+        .select_related('author')
+        .prefetch_related(
+            Prefetch(
+                'replies',
+                queryset=Comment.objects.select_related('author').order_by('-created_at', '-id'),
+            ),
+        )
+    )
+    created = Comment.history.filter(ticket_id=ticket.pk, history_type='+').only('id', 'history_change_reason')
+    via = {record.id: _via(record) for record in created}
+    # A comment is only ever changed by its author editing it.
+    edited = set(Comment.history.filter(ticket_id=ticket.pk, history_type='~').values_list('id', flat=True))
+    for comment in comments:
+        comment.via, comment.edited = via.get(comment.pk, ''), comment.pk in edited
+        for reply in comment.replies.all():
+            reply.via, reply.edited = via.get(reply.pk, ''), reply.pk in edited
+        entries.append(Entry(comment.created_at, comment.author, comment=comment))
+    # Newest first; replies under a comment are ordered the same way.
+    return sorted(entries, key=lambda entry: entry.when, reverse=True)

django_dg_board-1.0.0/src/datagroceries/board/admin.py

@@ -0,0 +1,45 @@
+from django.contrib import admin
+from simple_history.admin import SimpleHistoryAdmin
+
+from datagroceries.board.models import Attachment, Column, Comment, Group, Label, Relation, Ticket
+
+
+class ColumnInline(admin.TabularInline):
+    model = Column
+    extra = 0
+
+
+@admin.register(Group)
+class GroupAdmin(SimpleHistoryAdmin):
+    list_display = ('name', 'slug', 'position')
+    inlines = (ColumnInline,)
+
+
+@admin.register(Ticket)
+class TicketAdmin(SimpleHistoryAdmin):
+    list_display = ('__str__', 'column', 'assignee', 'size', 'is_blocked', 'closed_at')
+    list_filter = ('column__group', 'column__category', 'is_blocked')
+    search_fields = ('title',)
+    raw_id_fields = ('creator', 'assignee')
+    filter_horizontal = ('labels',)
+
+
+@admin.register(Relation)
+class RelationAdmin(SimpleHistoryAdmin):
+    list_display = ('source', 'type', 'target')
+    raw_id_fields = ('source', 'target')
+
+
+@admin.register(Comment)
+class CommentAdmin(SimpleHistoryAdmin):
+    list_display = ('__str__', 'author', 'sets_blocked', 'created_at')
+    raw_id_fields = ('ticket', 'author', 'parent')
+
+
+admin.site.register(Label)
+
+
+@admin.register(Attachment)
+class AttachmentAdmin(admin.ModelAdmin):
+    list_display = ('name', 'ticket', 'content_type', 'size', 'uploaded_by', 'uploaded_at')
+    raw_id_fields = ('ticket', 'uploaded_by')