Rename member handle slug/active_slug → username everywhere

[wintermeyer]

TL;DR

Renames a member's handle from slug/active_slug to username across the database, schema, JSON/API, the change-username feature, and the docs — so the name finally matches what humans (and the UI) call it. Tags keep slug (a genuinely derived slug); the generic URL-routing slug machinery keeps slug too. Breaking for /api/2.0 + agent-format consumers (handle field is now username; agent-doc schema_version 2 → 3). The DB rename is lossless but not blue/green-safe, so it must ship as a deliberate planned-downtime deploy (like the UUID v7 re-key), not a casual push to main.

What changed

• DB (lossless RENAME): users.active_slug → users.username; slug_changes → username_changes; indexes/constraints renamed to match (the users unique index too, so unique_constraint(:username) keeps mapping the "taken" error).
• Schema/code: field :username, Phoenix.Param key, get_user_by_username, update_username, username_changeset, username_change_quota, username_taken?, UsernameChange, plus registration / notification (actor_username) / image-rebuild helpers.
• API/JSON (breaking): handle field is username (was slug); replies/authors use author_username; agent-doc schema_version 2 → 3.
• Feature: SlugController + /slugs → UsernameController + /usernames.
• Docs: /developers reference + data model, README, robots/llms.

Deliberately kept as slug

The URL-path-segment machinery (:slug route param, ReservedSlugs, ResolveSlug/ResolveOwnedSlug/UserResolveSlug, SlugHelpers) and a tag's slug — "slug" is the correct web term there and is shared with tags. Gettext %{slug} placeholders are invisible internal names (rendered output is the real @username).

Safety / deploy

• Pure renames — no data moved or dropped; the migration has a full down.
• NOT N-1 safe: the previous release still queries active_slug/slug_changes. Ship as a planned-downtime deploy.
• mix precommit green (1922 tests, credo --strict, format, warnings-as-errors). Verified in the running app: profile/endorsers JSON now carry username, /usernames/new resolves, old /slugs/* 404s.

On merge / deploy

• Bump mix.exs (currently 6.3.0) as part of the push to main — this is a notable breaking change.
• Local note: I migrated the dev DB to the new schema for verification. To run main locally again, mix ecto.rollback this migration (it's reversible) or stay on the branch.

https://claude.ai/code/session_01SXxEH6QnfZbhvAWsDLtCiH

[wintermeyer]

Data-safety verification (no data lost or deleted)

Proven, not just asserted:

1. The migration only renames. No DROP/DELETE/TRUNCATE, no column type change, no add/remove/modify, no @disable_ddl_transaction — 12 RENAME statements that run atomically in the default DDL transaction, so a failure rolls back whole (no partial/corrupt state).

2. Round-trip on the real dev DB (60,538 users, 3 username_changes). Content fingerprint md5(string_agg(id || handle order by id)):

step	users fp	username_changes fp
before (username schema)	7d8c7e8b…251c	850d5977…4c79
after ecto.rollback (active_slug/slug_changes)	7d8c7e8b…251c ✅	850d5977…4c79 ✅
after re-ecto.migrate (username schema)	7d8c7e8b…251c ✅	850d5977…4c79 ✅

Identical at every step → the up/down round-trip is byte-for-byte lossless on real data. Final schema lands on users.username + users_username_index + username_changes (pkey/fk/index renamed); the only remaining slug indexes are tags.slug and work_experiences.slug (genuinely-derived slugs, correctly kept).

3. mix precommit green (1922 tests) and verified in the running app: profile/endorsers JSON carry username, /usernames/new resolves, old /slugs/* 404s.

Documentation — fully updated

README (schema list, admin SQL, username-change feature, data export), /developers (data-model, reference, index, cookbook), llms.txt, robots.txt, and code moduledocs/comments (avatar/cover filename examples, Phoenix.Param, regenerator, post system-message handle, errors.pot rule comment). Deliberately kept as slug: the :slug URL route param, ReservedSlugs/Resolve*Slug/SlugHelpers (routing + generation, shared with tags), a tag's / work-experience's derived slug, the internal @handle search field, and gettext %{slug} placeholders.