CodeForPhilly / CodeForPhilly/codeforphilly-ng

Post-cutover: migrate body-heavy entities to gitsheets v1.2 content-typed (markdown) records

Đang mở
#44 1 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
TypeScript
Star
1
Fork
1
Merge trung bình
5 ngày 3 giờ
Pull request đã merge (30 ngày)
9

Mô tả

[gitsheets v1.2.0](https://github.com/JarvusInnovations/gitsheets/releases/tag/v1.2.0) added content-typed records — sheets opt into `format.type = 'markdown'` to store records as `.md` files with TOML frontmatter and a designated body field. Plus lazy body loading via `query({ withBody: false })`.

This is the biggest one-time upgrade we'd take from the gitsheets 1.x line. Not urgent — defer to **after `cutover-prep` ships** so we're not refactoring entities mid-migration.

## Why migrate

- **Snapshot is actually-readable.** Contributors cloning `codeforphilly-data-snapshot` see real `.md` files in any markdown viewer — instead of parsing TOML records to find the prose.
- **Authoring via PR.** Staff / maintainers can edit a project overview in any markdown editor and PR it; currently they roundtrip through the API.
- **Listing performance.** `queryAll({ withBody: false })` on hot paths: projects-index, activity feed, FTS seeding, snapshot scrub.
- **Indexes stay fast.** Index builds use body-less reads natively in v1.2.

## What changes

Entities with substantial body content:
- `Project` — `overview` (markdown body), `summary` (short markdown) → migrate `overview` as the body field, keep `summary` in frontmatter
- `ProjectUpdate` — `body` (markdown) → migrate `body` as the body field
- `ProjectBuzz` — `summary` (markdown) → migrate as body
- `Person` — `bio` (markdown) → migrate as body
- `HelpWantedRole` — `description` (markdown) → migrate as body
- `Tag` — `description` (markdown, short) → optional; cheaper to leave as TOML field

The migration is bounded; entities without long bodies (`ProjectMembership`, `SlugHistory`, `Revocation`, `TagAssignment`, `HelpWantedInterestExpression`) stay as TOML records.

## Tasks

1. Schema reshape in `packages/shared/src/schemas/` — one designated body field per content-typed entity (rename or restructure the existing `overview` / `body` / `bio` / `description` / `summary` fields).
2. Update `.gitsheets/.toml` configs with `[gitsheet.format] type = 'markdown' body = ''`.
3. In-memory loader in `apps/api/src/store/memory/loader.ts` — use `{ withBody: false }` for index-building reads; lazy-load via `Sheet.loadBody(record)` when serving record detail responses.
4. Serializers in `apps/api/src/services/serializers/` — `*Html` / `*Excerpt` derived from the body field instead of the legacy string field.
5. FTS pipeline in `apps/api/src/store/fts.ts` — body included in the indexed text via lazy-load batch.
6. `apps/api/scripts/import-laddr.ts` — write the new markdown format for migrated entities.
7. `apps/api/scripts/scrub-data.ts` — the snapshot now contains real `.md` files; verify the scrub still strips PII correctly across the new file shape.
8. The data repo's existing TOML records need migration once — write a one-shot `apps/api/scripts/migrate-to-content-typed.ts` that reads existing records and rewrites as `.md` per the new format.
9. Update `specs/behaviors/markdown-rendering.md` and `specs/data-model.md` to reflect content-typed entities.

## Why defer

- `cutover-prep` is next and depends on every other plan; this would invalidate frozen plans (`storage-foundation`, `read-api`, `write-api`, `laddr-import`, `public-snapshot-scrub`).
- The benefit is real but landing is post-cutover work, not pre-cutover refactor.

## Out of scope

- `gitsheets check` pre-commit hooks belong in the data repo, not this code repo.
- The bundled Claude Code skill at `node_modules/gitsheets/skills/gitsheets/` is available once we bump the dep range; future plans touching gitsheets can load it.

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Hướng nghiên cứu

Bắt đầu với các schema trong packages/shared/src/schemas/ và các cấu hình .gitsheets/.toml, sau đó kiểm tra apps/api/src/store/memory/loader.ts để tìm các lần đọc không có body và các lần đọc chi tiết. Theo dõi các serializer, pipeline FTS, import-laddr.ts, scrub-data.ts và script migrate-to-content-typed.ts đã được lên kế hoạch. Được xem là hoàn tất khi các entity được liệt kê sử dụng định dạng markdown mới, các lần đọc và index xử lý các body được tải lười, dữ liệu hiện có được migrate an toàn và cả hai đặc tả đều được cập nhật.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
markdown, typescript
Lĩnh vực
api, backend, databases, documentation
Loại issue
Tái cấu trúc
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Đặc tả rõ ràng
Mức phù hợp với người mới
35/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.