From 256fd7a56ef6326b32c913526fa6d882d10bcfd4 Mon Sep 17 00:00:00 2001 From: Chris Alfano Date: Wed, 14 Oct 2026 00:25:04 -0400 Subject: [PATCH 1/2] docs(specs): year-partitioned markdown event records; a program is a series of days Three decisions from review: - Events are partitioned by year on disk (`events//.md`) and stored as content-oriented records with the description as the markdown body; series records likewise; RSVPs sit under the event's year. Monthly events accrete forever and the flat directory would not. - A series is a program instance ("Launchpad 2018") or an open-ended set ("Monthly Hack Nights"); "Launchpad" alone is not one. A multi-day program is a series of per-day events, each with its own venue, RSVPs and agenda of time slots. New principle: one venue, one span, one event. - The four laddr events therefore backfill as series, and the legacy `/events/` URLs redirect to the series page. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01WVK3JSficcyHViXj36opqV --- specs/behaviors/events.md | 19 ++++++++++--------- specs/behaviors/legacy-id-mapping.md | 4 ++-- specs/behaviors/storage.md | 6 +++--- specs/data-model.md | 26 ++++++++++++++------------ specs/deferred.md | 6 ------ 5 files changed, 29 insertions(+), 32 deletions(-) diff --git a/specs/behaviors/events.md b/specs/behaviors/events.md index 72088aa..18da4b7 100644 --- a/specs/behaviors/events.md +++ b/specs/behaviors/events.md @@ -2,9 +2,9 @@ ## Rule -An **event** is a single, dated gathering Code for Philly hosts — a monthly hack night, a showcase, a workshop. Staff create them on the site, members RSVP on the site, and the site is the system of record for when, where, and who's going. Meetup.com is no longer the source of truth; while the community transitions, an event may carry a link to its Meetup listing, but the site's own RSVP is always the primary call to action. +An **event** is a single gathering Code for Philly hosts at one venue over one contiguous span — a monthly hack night, a showcase, a workshop, one day of a hackathon. Staff create them on the site, members RSVP on the site, and the site is the system of record for when, where, and who's going. Meetup.com is no longer the source of truth; while the community transitions, an event may carry a link to its Meetup listing, but the site's own RSVP is always the primary call to action. -This is the scope [issue #194](https://github.com/CodeForPhilly/codeforphilly-ng/issues/194) asks for: an easy-to-remember `/events` page, member RSVPs, calendar files, reminder emails, and a short list on the home page. Events are **flat** — one record is one thing you RSVP to — and two optional structures hang off them: a [series](#series) ("Monthly Hack Nights") and an [agenda](#agenda) (the timed schedule inside a big event). Together they cover what laddr's program-with-sessions model did for Launchpad without making sessions their own records. +This is the scope [issue #194](https://github.com/CodeForPhilly/codeforphilly-ng/issues/194) asks for: an easy-to-remember `/events` page, member RSVPs, calendar files, reminder emails, and a short list on the home page. Events are **flat** — one record is one thing you RSVP to — and two optional structures hang off them: a [series](#series) ("Launchpad 2018", "Monthly Hack Nights") and an [agenda](#agenda) (the time slots within one event). A multi-day program is a series of per-day events, each with its own venue and agenda; that is how laddr's program-with-sessions model maps onto records people can actually RSVP to. ## Applies To @@ -55,9 +55,10 @@ An event is **upcoming** while `endsAt > now` and **past** once `endsAt ≤ now` ## Series -An **event series** is a named grouping with no dates of its own: "Monthly Hack Nights", "Launchpad", "Open Data Workshops". An event belongs to at most one series (`seriesId`), and a series has any number of events across any span of time. +An **event series** is a named grouping with no dates of its own. It takes two shapes: a **program instance** such as "Launchpad 2018" or "DataHack 2020", whose days are its events — the Friday kickoff at City Hall, the Saturday work day at the Innovation Lab, the showcase night at Indy Hall — and an **open-ended set** such as "Monthly Hack Nights" or "Open Data Workshops" that accretes one event at a time. "Launchpad" by itself is not a series; each year's program is. An event belongs to at most one series (`seriesId`), and a series has any number of events across any span of time. -- A series is **not** a recurrence rule and generates nothing. It is a label with a page. The [One record per occurrence](#principles) principle stands: every hack night is still its own record. +- A series is **not** a recurrence rule and generates nothing. It is a label with a page. The [One record per occurrence](#principles) principle stands: every hack night, and every day of a Launchpad, is still its own record with its own venue, RSVPs, and reminders. +- The series page is where a program reads as a whole: its description above, then its events in order, each with its venue and date. Nothing about the series record changes when days are added. - The event detail page shows "Part of " linking to `/events/series/`; the series page lists its upcoming events first, then past, with the series description above. - Duplicating an event keeps its series. That is how the monthly hack night accumulates under one heading with no extra typing. - Staff manage series from the event form (pick an existing one or create inline) and from the series page (edit title and description). A series can be deleted only when no event references it. @@ -65,11 +66,11 @@ An **event series** is a named grouping with no dates of its own: "Monthly Hack ## Agenda -An event may carry an **agenda**: an ordered list of timed items embedded in the record (laddr's `EventSegment`, without the separate table). A hack night has none. A Launchpad weekend has a dozen. +An event may carry an **agenda**: an ordered list of time slots within that one event, embedded in the record. A hack night has none. The Saturday of a Launchpad has a dozen — opening remarks, team formation, workshops, lunch, open hacking, dinner, close — all at that day's venue. -- Each item has a start time, an optional end, a title, an optional venue override, and an optional markdown description. Items sit within the event's own time range and are kept sorted by start. +- Each item has a start time, an optional end, a title, an optional venue override (a room, a nearby spot for dinner — never a different day or a different event's venue), and an optional markdown description. Items sit within the event's own time range and are kept sorted by start. - The detail page renders a non-empty agenda as the **Schedule** sidebar, grouped by day in `America/New_York` ("**Friday,** March 31"), each item showing its compact time range ("6–9pm", "9am–7pm"), its title, and its description. A venue is shown with a map-pin and a Google Maps link only when it differs from the previous item's venue, where an item without a venue override is at the event's venue and each day starts from the event's venue — this is laddr's schedule sidebar, which was the best piece of the old UI. -- Agenda items have no identity: no slug, no page, no RSVP, no reminder. "Going to Showcase Night" means RSVPing to the event that contains it. If a session genuinely needs its own RSVP list, it becomes its own event in the same series ([deferred.md](../deferred.md#per-session-rsvps-on-multi-day-events)). +- Agenda items have no identity: no slug, no page, no RSVP, no reminder. Anything someone would RSVP to on its own — a day, a showcase night — is an event in the series, not an agenda item. - The agenda is **not** exported as separate calendar entries; the event's `.ics` `DESCRIPTION` includes a plain-text rendering of the schedule after the description. - Agenda edits bump nothing and email nobody. Only the event-level time and location fields trigger the "event updated" mail. @@ -164,7 +165,7 @@ The form is a convenience, not the only door. `POST /api/events` is the same wri ## Legacy URLs -Laddr served `/events`, `/events/*past`, `/events/*upcoming`, `/events/*all`, `/events/`, and `/events//segments/`. The rewrite answers them per [legacy-id-mapping.md](legacy-id-mapping.md#legacy-url-forms-we-accept): the starred list views 301 to `/events/past` or `/events`; the four historical laddr events are backfilled with their slugs preserved, their segments as agenda items, and a "Launchpad" series grouping the three Launchpads, so `/events/launchpad-2023` keeps resolving; segment URLs 301 to the event's schedule anchor. +Laddr served `/events`, `/events/*past`, `/events/*upcoming`, `/events/*all`, `/events/`, and `/events//segments/`. A laddr "event" was a whole program, so each of the four becomes a **series** whose slug is the laddr handle, with one event per day of segments and that day's segments as its agenda. The rewrite answers the old URLs per [legacy-id-mapping.md](legacy-id-mapping.md#legacy-url-forms-we-accept): the starred list views 301 to `/events/past` or `/events`; `/events/` and its segment URLs 301 to `/events/series/`. ## Principles @@ -174,7 +175,7 @@ Laddr served `/events`, `/events/*past`, `/events/*upcoming`, `/events/*all`, `/ - **Philly time, always.** When a time could be shown in the viewer's zone or in `America/New_York`, show Philly time with its abbreviation. The event is in one place; the page should agree with the sign on the door. - **One record per occurrence.** When a feature tempts a recurrence rule or a template that generates events, reach for "duplicate" instead. A series is a label, never a generator. Every occurrence is an independent, editable, cancellable record with its own RSVPs; the data repo's history shows what was actually announced, not what a rule would have produced. -- **Sessions don't get identity until they need RSVPs.** An agenda item is a line in a schedule. The moment someone needs to RSVP to it, reminder for it, or link to it on its own, it becomes an event in the same series — not a new kind of record. +- **One venue, one span, one event.** An event is a place and a contiguous stretch of time. When a program changes venue or crosses into another day, that is another event in the same series; the agenda only ever subdivides the time inside one event. Modelling a weekend as one event with a venue per agenda item is the mistake this rules out. - **Our RSVP is the call to action.** Any link to an external listing (Meetup, Eventbrite, tickets) is secondary in position and weight. The site is displacing Meetup, not pointing at it. - **RSVPs are public.** The attendee list is the feature, and the data repo is public anyway. Never add a privacy knob the storage can't honor. - **The write never waits on the mail.** RSVP, cancel, and update succeed whether or not email delivers; reminders are at-most-once. A missed email is recoverable from the site; a duplicate or a failed RSVP is not. diff --git a/specs/behaviors/legacy-id-mapping.md b/specs/behaviors/legacy-id-mapping.md index 65d5743..f87146c 100644 --- a/specs/behaviors/legacy-id-mapping.md +++ b/specs/behaviors/legacy-id-mapping.md @@ -44,8 +44,8 @@ The web layer catches these patterns and 301s to the canonical URL: | `/tags/` | `/tags//` | split on `.` | | `/events/*past` | `/events/past` | static rewrite | | `/events/*upcoming`, `/events/*all` | `/events` | static rewrite | -| `/events/` | unchanged | the four laddr events are backfilled with their handles as slugs ([events.md](events.md#legacy-urls)) | -| `/events//segments/` | `/events/#schedule` | segments became agenda items on the event; no page of their own | +| `/events/` | `/events/series/` | a laddr event was a whole program; each is backfilled as a series with its handle as slug ([events.md](events.md#legacy-urls)) | +| `/events//segments/` | `/events/series/` | segments became that series' per-day events and their agenda items; no page per segment | | `/calendar` | `/events` | static rewrite (not a laddr URL; the issue asked for the alias) | Patterns not listed (e.g., `/checkin`, `/bigscreen`) return 410 Gone with an explanation page (see [deferred.md](../deferred.md) for why those URLs no longer exist). diff --git a/specs/behaviors/storage.md b/specs/behaviors/storage.md index 6069b8c..3c84107 100644 --- a/specs/behaviors/storage.md +++ b/specs/behaviors/storage.md @@ -113,9 +113,9 @@ Each entity lives in one sheet. The path template determines how records are sto | BlogPost | `blog-posts` | `blog-posts/${slug}.md` (markdown format, body in `body`) | | HelpWantedRole | `help-wanted-roles` | `help-wanted-roles/${projectSlug}/${id}.toml` | | HelpWantedInterestExpression | `help-wanted-interest` | `help-wanted-interest/${roleId}/${personSlug}.toml` | -| Event | `events` | `events/${slug}.toml` | -| EventRsvp | `event-rsvps` | `event-rsvps/${eventSlug}/${personSlug}.toml` | -| EventSeries | `event-series` | `event-series/${slug}.toml` | +| Event | `events` | `events/${year}/${slug}.md` — markdown body `description`; `year` rendered from `startsAt` | +| EventRsvp | `event-rsvps` | `event-rsvps/${year}/${eventSlug}/${personSlug}.toml` | +| EventSeries | `event-series` | `event-series/${slug}.md` — markdown body `description` | | Tag | `tags` | `tags/${namespace}/${slug}.toml` | | TagAssignment | `tag-assignments` | `tag-assignments/${taggableType}/${taggableId}/${tagId}.toml` | | SlugHistory | `slug-history` | `slug-history/${entityType}/${oldSlug}.toml` | diff --git a/specs/data-model.md b/specs/data-model.md index c6bad15..60fe1e1 100644 --- a/specs/data-model.md +++ b/specs/data-model.md @@ -451,12 +451,13 @@ Used for the 30-day per-person-per-role rate cap on `POST /express-interest` (se ## Event _(new — replaces Meetup.com)_ -A single dated gathering: a hack night, a showcase, a workshop, a hackathon weekend. Staff-authored; members RSVP. Rules in [behaviors/events.md](behaviors/events.md). Events are **flat** — one record is one thing you can RSVP to. Two optional structures hang off it: a link to an [EventSeries](#eventseries-new) ("Monthly Hack Nights", "Launchpad 2023") and an embedded **agenda** of timed items, which together replace laddr's `Event` + `EventSegment` pair without making sessions their own RSVP-able records. +A single gathering at one venue over one contiguous span: a hack night, a workshop, one day of a hackathon. Staff-authored; members RSVP. Rules in [behaviors/events.md](behaviors/events.md). Events are **flat** — one record is one thing you can RSVP to. Two optional structures hang off it: a link to an [EventSeries](#eventseries-new) ("Launchpad 2018", "Monthly Hack Nights") and an embedded **agenda** of time slots within the event. A program that moves between venues or spans days is a series of events, not one event. **Sheet:** `events` -**Path template:** `events/${slug}.toml` +**Path template:** `events/${year}/${slug}.md` where `year` is rendered from `startsAt` (`${{ startsAt.slice(0, 4) }}` — the UTC year) +**Format:** `markdown` — the `description` field is the file body, after `+++` TOML frontmatter, like blog posts -The default slug is date-first (`2026-11-03-hack-night`) so the sheet directory lists chronologically when browsed in the data repo. +The sheet is partitioned by year because monthly events accrete forever; within a year the default slug is date-first (`2026-11-03-hack-night`) so the directory lists chronologically when browsed in the data repo. The slug stays globally unique — the year is a storage partition, not part of the URL. | Field | Type | Notes | | ------- | ------ | ------- | @@ -464,7 +465,7 @@ The default slug is date-first (`2026-11-03-hack-night`) so the sheet directory | legacyId | int nullable | laddr `events.ID` for the four backfilled historical events. | | slug | string | unique. URL: `/events/`. See [behaviors/slug-handles.md](behaviors/slug-handles.md). | | title | string | required, 1–200 chars | -| description | string nullable | markdown, ≤ 20,000 chars | +| description | string nullable | markdown, ≤ 20,000 chars — the file body | | startsAt | iso8601 | required | | endsAt | iso8601 | required; strictly after `startsAt` | | venueName | string nullable | ≤ 120 chars | @@ -518,17 +519,18 @@ Items are kept sorted by `startsAt` on write; a cap of 50 items per event keeps ## EventSeries _(new)_ -A named, open-ended grouping of events: "Monthly Hack Nights", "Launchpad 2023", "Open Data Workshops". It carries no dates of its own — its events do — and takes no RSVPs. It exists so the detail page can say "Part of Monthly Hack Nights", so a series page can list every occurrence past and future, and so duplicating an event carries the grouping forward. +A named grouping of events. Two shapes share the record: a **program instance** — "Launchpad 2018" is a series whose three days are its events, each with its own venue and agenda — and an **open-ended set** — "Monthly Hack Nights" accretes one event a month. A series carries no dates of its own (its events do) and takes no RSVPs. It exists so the detail page can say "Part of Launchpad 2018", so a series page can list every event past and future, and so duplicating an event carries the grouping forward. "Launchpad" alone is not a series; each year's program is. **Sheet:** `event-series` -**Path template:** `event-series/${slug}.toml` +**Path template:** `event-series/${slug}.md` +**Format:** `markdown` — the `description` field is the file body | Field | Type | Notes | | ------- | ------ | ------- | | id | uuid | | | slug | string | unique. URL: `/events/series/`. | | title | string | required, 1–120 chars | -| description | string nullable | markdown, ≤ 10,000 chars | +| description | string nullable | markdown, ≤ 10,000 chars — the file body | | createdAt | iso8601 | | | updatedAt | iso8601 | | @@ -543,9 +545,9 @@ A named, open-ended grouping of events: "Monthly Hack Nights", "Launchpad 2023", A member's public "I'm going" for an event. Existence means going; there is no status field. After RSVPing the member may answer one follow-up — what they're coming to do — which is what the attendee list groups by. **Sheet:** `event-rsvps` -**Path template:** `event-rsvps/${eventSlug}/${personSlug}.toml` +**Path template:** `event-rsvps/${year}/${eventSlug}/${personSlug}.toml` — `year` is the event's partition year, written onto the record by the write service alongside `eventSlug` and `personSlug` -The composite path makes "who's going to event X" a directory scan and "has this person RSVP'd" a path-exists test. Renaming an event's slug moves its RSVP files in the same commit. +The composite path makes "who's going to event X" a directory scan and "has this person RSVP'd" a path-exists test, and the year partition keeps the top-level directory bounded the same way `events/` is. Renaming an event's slug moves its RSVP files in the same commit. | Field | Type | Notes | | ------- | ------ | ------- | @@ -646,9 +648,9 @@ Cascading deletes are not enforced by gitsheets; the API's mutation services del | Database tables | gitsheets sheets | | `INDEX`, `UNIQUE INDEX` | enforced in-process by the API under the write mutex; backed by in-memory indices built at boot | | `FOREIGN KEY ... ON DELETE CASCADE` | atomic multi-record gitsheets commit (see Storage spec) | -| `events.Handle` / `Title` / `StartTime` / `EndTime` / `LocationName` / `LocationAddress` / `Description` / `Status` | `Event.slug` / `title` / `startsAt` / `endsAt` / `venueName` / `venueAddress` / `description` / `status` (`published` → `scheduled`, `deleted` → not imported) | -| `event_segments.Title` / `StartTime` / `EndTime` / `LocationName` / `LocationAddress` / `Summary` + `Description` | `Event.agenda[]` items: `title` / `startsAt` / `endsAt` / `venueName` / `venueAddress` / `description` (summary and description concatenated) | -| _(no laddr equivalent; Launchpads were standalone events)_ | `event-series` sheet — "Launchpad", "Monthly Hack Nights" | +| `events.Handle` / `Title` / `Description` (a laddr "event" was a whole program) | `EventSeries.slug` / `title` / `description` | +| `event_segments` grouped by calendar day (`LocationName` / `LocationAddress` of the day's first segment) | one `Event` per day in that series: `venueName` / `venueAddress`, `startsAt`/`endsAt` spanning the day's segments, slug `-` | +| `event_segments.Title` / `StartTime` / `EndTime` / `Summary` + `Description` | `Event.agenda[]` items on that day's event: `title` / `startsAt` / `endsAt` / `description` (summary and description concatenated) | | Meetup.com RSVPs (never in laddr's DB) | `event-rsvps` sheet | | `member_checkins` | _dropped — see [deferred.md](deferred.md)_ | | `Emergence\CMS\BlogPost` | _dropped — see [deferred.md](deferred.md)_ | diff --git a/specs/deferred.md b/specs/deferred.md index 565b32a..f29515d 100644 --- a/specs/deferred.md +++ b/specs/deferred.md @@ -71,12 +71,6 @@ When a deferred item is promoted, move it from this file into the relevant spec, - **Why deferred:** RSVP records live in the public data repo, and the attendee list is the feature ([behaviors/events.md](behaviors/events.md#rsvps-are-public)). A "hide me" flag on the public record would be a promise the storage can't keep. - **When promoted:** Keep the public record as the only thing the attendee list reads, and add a *supplemental* private RSVP record in the private store ([behaviors/private-storage.md](behaviors/private-storage.md)) for members who choose "RSVP privately". Private RSVPs count toward `rsvpCount` only as an aggregate ("14 going · 2 private"), receive the same confirmation and reminder emails, and never produce a public file. The reminder sweep would read both stores. -### Per-session RSVPs on multi-day events - -- **What:** RSVPing to one agenda item of a big event ("just the Showcase Night") rather than the whole thing. -- **Why deferred:** Agenda items are embedded in the event record and carry no identity ([data-model.md](data-model.md#agenda-items)). The four historical Launchpads are the only events that ever had sessions, and they handled per-session tickets off-site. -- **When promoted:** Make each session its own flat `Event` in the same `EventSeries`. The series page already renders them as a day-grouped schedule; nothing about the record shape changes. - ### Event recurrence - **What:** "Every first Tuesday" rules that generate occurrences. From 00b40b307a3a720a88fa3ebe9eafaa5a55a6b17b Mon Sep 17 00:00:00 2001 From: Chris Alfano Date: Wed, 14 Oct 2026 00:25:43 -0400 Subject: [PATCH 2/2] chore(plans): add events-storage-layout; backfill becomes series of days The backfill plan now depends on the layout change and writes one series per laddr program with one event per day of segments. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01WVK3JSficcyHViXj36opqV --- plans/events-legacy-backfill.md | 98 ++++++++++++++++------------- plans/events-storage-layout.md | 105 ++++++++++++++++++++++++++++++++ 2 files changed, 161 insertions(+), 42 deletions(-) create mode 100644 plans/events-storage-layout.md diff --git a/plans/events-legacy-backfill.md b/plans/events-legacy-backfill.md index 7c37928..1a6294c 100644 --- a/plans/events-legacy-backfill.md +++ b/plans/events-legacy-backfill.md @@ -1,6 +1,6 @@ --- status: planned -depends: [events-series-agenda] +depends: [events-storage-layout] specs: - specs/behaviors/events.md - specs/behaviors/legacy-id-mapping.md @@ -12,31 +12,32 @@ issues: [194] ## Scope -Laddr held exactly four events (`launchpad-2018`, `launchpad_2019`, -`datahack2020`, `launchpad-2023`), each with a handful of schedule segments. -Carry them into the `events` sheet so `/events/past` has history and the old -URLs keep resolving. - -**In:** four hand-authored event records plus one `event-series` record -("Launchpad", grouping the three Launchpads) on the data repo's `published` -branch (via PR, per that repo's conventions), with `legacyId`, original -handles as slugs, `status: scheduled`, and each laddr segment carried as an -`agenda` item (title, times, venue, summary + description). Legacy -`/thumbnail//…` images referenced in descriptions are captured as -attachments and rewritten, per +Laddr held exactly four "events" (`launchpad-2018`, `launchpad_2019`, +`datahack2020`, `launchpad-2023`), each a multi-week program with a handful +of schedule segments. Under the data model each is a **series** whose days +are events: carry them into the `event-series` and `events` sheets so +`/events/past` has history and the old URLs keep resolving. + +**In:** one `event-series` record per laddr event (slug = laddr handle, +title and description from the program), one `events` record per calendar +day of segments (slug `-`, venue from the day's +first segment, span from the day's first start to its last end, the day's +segments as `agenda` items), legacy `/thumbnail//…` images captured as +attachments on the event whose text references them and rewritten per [legacy-id-mapping.md](../specs/behaviors/legacy-id-mapping.md#legacy-resources-captured-at-import-time-not-proxied-at-runtime). +Committed through gitsheets on a branch of the data repo for a PR into +`published`. -**Out:** per-session events -([deferred.md](../specs/deferred.md#per-session-rsvps-on-multi-day-events)); -any Meetup check-in history (dropped). +**Out:** any Meetup check-in history (dropped); RSVPs for historical +events (there were none on the site). ## Implements - [behaviors/events.md](../specs/behaviors/events.md#legacy-urls). - [legacy-id-mapping.md](../specs/behaviors/legacy-id-mapping.md#legacy-url-forms-we-accept) — - `/events/` and `/events//segments/` rows. -- [data-model.md](../specs/data-model.md#event) — `legacyId` on Event and - the naming-map rows. + `/events/` and `/events//segments/` → the series page + (the redirect itself ships in `events-storage-layout`). +- [data-model.md](../specs/data-model.md#event) — the laddr naming-map rows. ## Approach @@ -44,36 +45,49 @@ any Meetup check-in history (dropped). `/events//segments?format=json`), captured in the research scratchpad during spec work; re-fetch from `codeforphilly.live.k8s.phl.io` if needed while it's up. -2. Write a one-off script under `apps/api/scripts/` that translates each - event (epoch → ISO UTC, `Status` → `scheduled`, each segment → an - `agenda` item with `Summary` and `Description` joined by a blank line; - the one segment whose `EndTime` precedes its `StartTime` gets `endsAt` - dropped) and emits the TOML via the gitsheets API against a working clone - of the data repo. The three Launchpads get `seriesId` of the "Launchpad" - series; DataHack stands alone. -3. Open the data-repo PR; merge to `published`; the hot-reload webhook - picks it up. -4. Add the `/events//segments/` → `/events/#schedule` - rewrite to `plugins/legacy-redirect.ts`. +2. `apps/api/scripts/backfill-laddr-events.ts` (already on the + superseded #213 branch, to be reworked): per laddr event, write the + series (description = the program's markdown, media rewritten, CRLF and + space-less headings normalized); group its segments by Philadelphia + calendar day; per day write an event titled after the day's first + segment (or " — " when the first segment is + generic), `venueName`/`venueAddress` from the first segment that has one, + `startsAt` = first start, `endsAt` = last end (or last start + 1h), the + day's segments as agenda items (a segment whose `EndTime` precedes its + `StartTime` keeps `startsAt` only). Images referenced by a segment go on + that day's event; images referenced by the program description go on + the series (series are content records too) — if series attachments are + not supported by the config, fall back to the first day's event and + rewrite accordingly. +3. Re-runnable: series match by slug, events by `(seriesId, date)`; + an unchanged run is a no-op commit. Branch created from a parent ref + with raw `git update-ref`, then `transact({ parent, branch })`. +4. Regenerate codeforphilly-data #12 (close the old branch) and merge it + into `published` after the release that reads these sheets is live. ## Validation -- [ ] `/events/launchpad-2023`, `/events/launchpad_2019`, - `/events/datahack2020`, `/events/launchpad-2018` render on production - with the Schedule sidebar listing every laddr segment under its day with - time range and venue. -- [ ] `/events/series/launchpad` lists the three Launchpads under Past. +- [ ] `/events/series/launchpad-2023`, `/events/series/launchpad_2019`, + `/events/series/datahack2020`, `/events/series/launchpad-2018` render on + production, each listing its days under Past with venue and date. +- [ ] Each day's event renders its Schedule with every laddr segment of + that day, time range and venue. +- [ ] `/events/launchpad-2023` and + `/events/launchpad-2023/segments/friday_night_kickoff-2023` 301 to the + series page. - [ ] No description references `codeforphilly.org/thumbnail/…`. -- [ ] `/events/launchpad-2023/segments/friday_night_kickoff-2023` 301s to - the event's schedule anchor. -- [ ] `/events/past` shows the four events in reverse start order. +- [ ] `/events/past` shows the days in reverse start order. ## Risks / unknowns -- **Agenda range rule.** Laddr's `launchpad-2018` had segments with null - `EndTime` and one with end before start; the agenda validator requires - each item's start inside the event range, which these satisfy, but check - the event `endsAt` covers the last segment before importing. +- **Day boundaries.** Segments are grouped by Philadelphia day; a segment + that crosses midnight stays with the day it starts. The 2023 "Weekly + Hack Nights 4/4 – 5/9" was a single laddr segment on one evening and + becomes one event on that date with its description listing the other + dates. +- **Naming the day.** The first segment's title is the event title; for + 2018's work day that is "Work Day", for 2023's "Friday Night Kickoff" — + check the four programs by eye before merging #12. ## Notes diff --git a/plans/events-storage-layout.md b/plans/events-storage-layout.md new file mode 100644 index 0000000..52f23ec --- /dev/null +++ b/plans/events-storage-layout.md @@ -0,0 +1,105 @@ +--- +status: planned +depends: [events-series-agenda] +specs: + - specs/data-model.md + - specs/behaviors/storage.md + - specs/behaviors/events.md + - specs/behaviors/legacy-id-mapping.md +issues: [194] +--- + +# Plan: year-partitioned, content-oriented event records + +## Scope + +Change how event records sit in the data repo before any exist in +production: events partitioned by year and stored as markdown-bodied +records, series stored the same way, RSVPs partitioned under the event's +year. Plus the model clarification that a multi-day program is a series of +per-day events, which touches the legacy redirects. + +**In:** the three sheet configs on the data repo's `empty`, `fixture` and +`legacy-import` branches (path templates + `[gitsheet.format]`), mirrored +into `apps/api/gitsheets/`; the RSVP write path injecting `year`; the +`/events/` → `/events/series/` legacy redirect; tests and +the dev seed. No schema or contract change is expected — `description` +stays a string field; the format block only moves it to the file body. + +**Out:** `published` — the other session adopts there in lockstep with the +release (zero event records exist, so the new templates apply cleanly); +the backfill itself ([`events-legacy-backfill`](events-legacy-backfill.md), +which now depends on this plan). + +## Implements + +- [data-model.md](../specs/data-model.md#event) — Event / EventSeries / + EventRsvp sheet, path template and format lines; the laddr naming-map + rows. +- [behaviors/storage.md](../specs/behaviors/storage.md#sheet-layout) — + the three rows. +- [behaviors/events.md](../specs/behaviors/events.md#series) — the Series + and Agenda semantics (program instance = series of per-day events) and + the Legacy URLs paragraph; the "One venue, one span, one event" + principle. +- [behaviors/legacy-id-mapping.md](../specs/behaviors/legacy-id-mapping.md#legacy-url-forms-we-accept) — + `/events/` and segment rows now point at the series page. + +## Approach + +1. **Configs.** `events.toml`: `path = '${{ startsAt.slice(0, 4) }}/${{ slug }}'` + plus `[gitsheet.format] type = 'markdown', body = 'description'`. + `event-series.toml`: same format block, path unchanged. + `event-rsvps.toml`: `path = '${{ year }}/${{ eventSlug }}/${{ personSlug }}'`. + One commit per data branch (empty, fixture, legacy-import), PRs, then + mirror `empty`'s `.gitsheets/` into `apps/api/gitsheets/`. Contract + documents unchanged; `gitsheets contracts verify` before each push. +2. **Write path.** `withRsvpPath` adds `year` (the event's partition year, + `startsAt.slice(0, 4)`) next to `eventSlug` and `personSlug`; the sheet + guard test lists it under `WRITE_INJECTED_PATH_FIELDS['event-rsvps']`. + Event writes need nothing: gitsheets renders the year from `startsAt` + and splits `description` into the body on write, joins on read. +3. **Rename moves.** A slug rename already rewrites each RSVP file; a + `startsAt` change that crosses a year boundary must now move the event + file and every RSVP file too — handle both in `EventWriteService.update` + by deleting the old paths before the upsert whenever the partition year + or slug changes. +4. **Redirects.** `plugins/legacy-redirect.ts`: `/events/` whose + handle is a live series slug (and not a live event slug) 301s to + `/events/series/`; segment URLs 301 to the series page. +5. **Tests + seed.** Rename/boundary move cases; the redirect rows; the + events tests keep passing against markdown records (assert a created + event's file lands at `events//.md` via `git ls-tree`). + +## Validation + +- [ ] A created event lands at `events//.md` with its + description as the markdown body; reading it back through the API is + byte-for-byte the description that was sent. +- [ ] An RSVP lands at `event-rsvps///.toml`. +- [ ] Moving an event's `startsAt` across a year boundary moves its file + and its RSVP files in the same commit; renaming its slug still does. +- [ ] A series' description is the body of `event-series/.md`. +- [ ] `/events/launchpad-2023` 301s to `/events/series/launchpad-2023` when + that series exists and no event has that slug. +- [ ] `check:sheet-configs` matches `empty`; `check-contracts` unchanged. +- [ ] `npm run type-check && npm run lint && npm test` clean. + +## Risks / unknowns + +- **Markdown body + agenda descriptions.** Only the event's own + `description` becomes the body; agenda item descriptions stay as + frontmatter strings. Confirm gitsheets serializes an array of tables + with multi-line strings in frontmatter cleanly (blog posts have no + nested arrays). +- **Year partition is UTC.** `startsAt.slice(0, 4)` is the UTC year, so a + New Year's Eve evening in Philadelphia files under the next year. It is + a storage partition, invisible in URLs; accepted for determinism. + +## Notes + +(Populated at closeout.) + +## Follow-ups + +(Populated at closeout.)