Skip to content

dj-models: tighten admin fieldsets with Important Dates convention#11

Open
ashbrener wants to merge 1 commit into
dvf:masterfrom
ashbrener:convention/admin-fieldsets
Open

dj-models: tighten admin fieldsets with Important Dates convention#11
ashbrener wants to merge 1 commit into
dvf:masterfrom
ashbrener:convention/admin-fieldsets

Conversation

@ashbrener
Copy link
Copy Markdown

Summary

Expands the fieldsets rule in dj-models from a single guideline to a three-band semantic pattern:

  1. Untitled (None) fieldsetid + primary natural key only (e.g. email/slug). Identifiers always visible at top.
  2. Named semantic sections"Personal Info", "Details", "Role & Permissions", "Security", "Relations". Grouped by meaning, not DB column order.
  3. "Important Dates" (always last, title case) — every datetime field lands here (created_at, updated_at, deleted_at, last_login, date_joined).

Also adds add_fieldsets guidance for creation forms (User primarily) — minimal required fields only.

Motivation

The current rule says "place identifiers and timestamps in the first fieldset." In practice, production codebases separate the two bands — identifiers in the untitled top fieldset, dates in a trailing "Important Dates" section. The split makes the top of the change view focused (just identity), the middle scannable (domain grouped by meaning), and keeps low-attention temporal fields out of the way.

The Django admin itself uses "Important dates" (lowercase d) on the default User admin. Standardizing on title case ("Important Dates") matches the other fieldset names in the skill's convention.

What changes

skills/dj-models/SKILL.md — replaces the single fieldsets bullet with:

  • The three-band structure explained and exemplified
  • A list of reusable section names (Personal Info / Details / Role & Permissions / Security / Relations)
  • A new bullet for add_fieldsets on creatable models

Tradeoffs

  • Title case "Important Dates" vs Django default "Important dates" — minor deviation. Worth it for consistency with the other title-cased section names.
  • Rule could be tighter still (e.g., mandate exact section names) but leaving "Details" as a catchall lets teams name domain sections appropriately for their models.

Expands the fieldsets rule from a single "place id + timestamps in the
first fieldset" guideline to the three-band pattern production codebases
on this stack converge on:

1. Untitled (None) fieldset: id + primary natural key only
2. Named semantic sections: Personal Info, Details, Role & Permissions,
   Security, Relations — grouped by meaning, not DB order
3. "Important Dates" (always last, title case): every datetime field —
   created_at, updated_at, deleted_at, last_login, date_joined

Separating dates from identifiers keeps the top of the change view
focused on what identifies the record; named middle sections make domain
fields scannable; the trailing date block is low-attention where dates
deserve to be.

Also adds add_fieldsets guidance for models that support admin creation
(User primarily) — minimal form with just required fields for a new
record.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant