Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Abierto
  • ¿Algo no está bien?
#44 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Refactorización
Claridad
Bien especificado
Estado de actividad
Tranquilo
Stack tecnológico
markdown, typescript
Área
api, backend, databases, documentation

Línea de trabajo

Comienza con los esquemas de packages/shared/src/schemas/ y las configuraciones .gitsheets/.toml; después, inspecciona apps/api/src/store/memory/loader.ts para las lecturas sin body y las lecturas de detalle. Sigue los serializadores, la canalización de FTS, import-laddr.ts, scrub-data.ts y el script planificado migrate-to-content-typed.ts. Se considera terminado cuando las entidades enumeradas usan el nuevo formato markdown, las lecturas y los índices gestionan bodies cargados de forma diferida, los datos existentes se migran de forma segura y ambas especificaciones están actualizadas.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

gitsheets 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/<sheet>.toml configs with [gitsheet.format] type = 'markdown' body = '<fieldName>'.
  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.
Lenguaje dominante
TypeScript
Estrellas
1
Forks
1
Merge medio
11 min
PR fusionados (30 d)
22

Preparar el entorno

  • Incluye un Dockerfile o un archivo de Docker Compose
  • Sin plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de CodeForPhilly/codeforphilly-ng

Todos los issues de CodeForPhilly/codeforphilly-ng

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.