Skip to content

Move tag assignments into a tags field on the tagged record #257

Open

Description

@themightychris

Move tag assignments out of the tag-assignments cross-reference sheet and into a field on the record they tag, e.g. tags = ["topic.transit", "tech.python"] on each project and person. We want this; the open work is to assess the downsides and measure the effect on common queries before committing to it.

Why

  • An assignment is a bare link. TagAssignment holds tagId, taggableType, taggableId, an optional assignedById and createdAt. It's edited at the same moment, by the same person, as the record it tags (the project or profile edit form).
  • Deletes leave orphans. Removing a project or person means finding and deleting its assignment files separately. Cleaning up three spam projects on 2026-10-15 (data commit 0a2182df61) meant hunting down 8 stray assignment files, and purge needs its own tag-assignment step in project-purge.ts / person-purge.ts. With an array field, deleting the record takes its tags with it.
  • File count. published holds 7,725 assignment files (6,632 person, 1,093 project) as separate TOML records, so each re-tag is several file adds and deletes in a commit rather than a one-line diff on the record.

What would change

  • Schema: a tags array field on projects, people, help-wanted-roles, blog-posts (each taggable type), holding tag handles (namespace.slug) or tag ids. That choice is part of the assessment: handles read well in the record and in git diffs, but a tag rename then rewrites every record using it. Under specs/principles.md an off-path reference stays an id; handles would be a deliberate exception or need a rename cascade. Contract bumps for each sheet, and adoption on empty/fixture/legacy-import and published in lockstep.
  • A one-off migration folding tag-assignments/<type>/<id>/<tagId> into the owning records, then retiring the sheet (and its contract).
  • In memory: tagAssignmentsByTaggable becomes the record's own field; tagAssignmentsByTag (tag → taggables) is still needed and gets built from the arrays at load and by StateApply.
  • Writers: tag.write.ts applyTagsForEntity, project/person/help-wanted/blog writes, purge, slug renames.
  • Readers: serializers (project, person, tag, help-wanted), facets (store/memory/facets.ts), tag pages, moderation footprint, the importer.

Downsides to assess

  • Losing per-assignment metadata: assignedById and createdAt per assignment. Is anything using them (moderation, audit)? If yes: keep a smaller array of objects, or accept git history as the record.
  • Concurrent edits: tag changes and other edits to the same record now touch the same file. Writes are serialized by the mutex, so it's merge noise in history, not a race. Confirm.
  • Tag rename / merge / delete (staff tag tools): today that rewrites assignment records; it would rewrite every tagged record, possibly thousands of person files in one commit. How common is it?
  • Staff auto-creating tags on project save keeps working, but check the flow.
  • Legacy-import / re-import shape.

Performance to measure

Before and after, on the full published dataset:

  • Boot load time and memory (one fewer sheet, but bigger records; index build moves to the record loader).
  • GET /api/projects with tag= filters and facets (the hottest tag path), list and search.
  • GET /api/tags/:handle, /projects, /people (tag → taggables).
  • Project/person detail serialization.
  • Hot-reload (POST /api/_internal/reload-data) incremental apply when a project's tags change.
  • Write path: tagging a project (commit size and latency).

Acceptance

A short written assessment (downsides found, measured numbers, recommendation, handle-vs-id decision). If it goes ahead: spec changes (data-model, the four sheets, tag specs) and a plan, then the migration as its own lockstep release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions