docs: add migration.md

[Satarupa22-SD]

Description

Schema Changes

Schema Changes Made

• No schema changes
• Audit Log schema (auditlog.cue) changes
• Capability Catalog schema (capabilitycatalog.cue) changes
• Control Catalog schema (controlcatalog.cue) changes
• Enforcement Log schema (enforcementlog.cue) changes
• Evaluation Log schema (evaluationlog.cue) changes
• Guidance Catalog schema (guidancecatalog.cue) changes
• Mapping Document schema (mappingdocument.cue) changes
• Policy Document schema (policy.cue) changes
• Principle Catalog schema (principlecatalog.cue) changes
• Risk Catalog schema (riskcatalog.cue) changes
• Threat Catalog schema (threatcatalog.cue) changes
• Vector Catalog schema (vectorcatalog.cue) changes
• Other

Schema Change Details

<!-- If applicable, provide a brief summary or example of schema changes -->

Testing

• Unit tests added/updated
• Manual testing performed
• Test data updated (if applicable)

Related Issues

#372

Reviewer Hints

---

Self-review checklist

• This PR has content that was created with AI assistance.
  • I have read and followed the Generative AI Contribution Policy.
• I have the experience and knowledge necessary to answer maintainer questions about the content of this PR, without using AI.

[jpower432]

@eddie-knight Anything missing from this list that you see?

[eddie-knight]

Perhaps we shouldn't be going change-by-change with the migration guide, since that seems to have lost track of the final state. Not sure whether there are any other deltas, but families became groups by the final v1 release.

https://github.com/gemaraproj/gemara/blob/main/capabilitycatalog.cue#L19

[jpower432]

That makes sense. I think it might be good to capture in-between changes that were actually released. Maybe it would be useful if we track individual field changes in the table at the top like:

Before	After
families[]	groups[]
family[i].controls[]	controls[], control.family
metadata.applicability-categories[]	metadata.applicability-groups[]