Article Lifecycle and Renaming Policy

2026-03-04

Objective

Allow gradual article modernization on a live app suite without breaking active collections/routes.

Lifecycle States

• active: currently referenced by live collections; remains in service until replacement is completed.
• replacement-draft: new off-shoot article being prepared; not yet in live collections.
• deprecated: old article after replacement is complete and collections are switched.
• archived: fully retired and removed from active collection use.

Renaming Principle

• New article is treated as a new-born asset:
• new filename
• new slug
• new title/subtitle
• no requirement to inherit old naming conventions
• Legacy file stays active until replacement is fully ready and switched in collections.
• Deprecation happens only after switch-over is complete.

Required Steps for Rename/Replacement

1. Create a new replacement article file in docs/articles/ with canonical metadata/content.
2. Validate replacement article locally in ISR (direct article route and collection listing).
3. Update referencing collection files in docs/articles/collections/*.yaml to use the new slug.
4. Mark legacy file as deprecated in frontmatter:
5. editorial.status: deprecated
6. editorial.replacedBySlug: <new-slug>
7. editorial.deprecatedAt: YYYY-MM-DD
8. Add mapping entry to docs/shared/article-migration-ledger.yaml.
9. Validate ISR pages resolve the new slug and no active collection points to deprecated slug.

Non-Breaking Rule

• Replacement is complete only when collections have switched to new slug.
• Old article must remain active until switch-over is verified.
• Deprecated articles must not remain in active collection lists.