@scribe-platform/cli 0.7.0 → 0.9.0

package/skills/scribe-site-builder/recipes/schema.md

@@ -129,6 +129,30 @@ produced a clean commit, a green deploy, and no tracking at all.
 Cookieless, so it needs no consent banner, and `defer` keeps it off the
 critical path.
 
+## Changing a collection that already holds content
+
+`scribe schema apply <site> --file <spec>` upserts **one whole collection by
+name** — so the spec you send *is* the collection afterwards. A field you leave
+out is a field you removed. Read the current definition first
+(`scribe schema show <site> <collection>`), edit that, and send it back; never
+write a spec from memory for a collection that already exists.
+
+What each kind of change costs, because a schema edit and a content edit are
+different risks:
+
+| Change | Effect on existing entries |
+|---|---|
+| Add a field | Harmless. Existing entries read it as empty. Add `required: true` only if you're also filling it in, or every existing entry becomes invalid. |
+| Remove a field | The content files keep the value, but nothing reads it and the admin stops showing it. Effectively lost. |
+| Rename a field | There is no rename — it is a remove plus an add, and the old values do not follow. Moving them means editing every content file. |
+| Change a field's type | The declared type generates the build's validation, so an entry whose value no longer fits **breaks the site build** rather than failing quietly. |
+| Remove a collection | `scribe schema remove` **deletes its content folder too**. |
+
+So when someone asks to "rename that field" or "change services to use a number
+for price", say what it will do to the entries that already exist before you run
+it. On a form collection the same applies to its submissions, which are in the
+database and far harder to reconcile than files in a repo.
+
 ## From the CLI instead
 
 Useful when you want the schema without a checkout, or to inspect it while