docs: add extensibility and forward compatibility guidelines

[gsmith85]

Description

• Added "Extensibility and Forward Compatibility" section to the schema authoring guide.
• Defined standards for Open vs. Closed Enumerations to prevent breaking changes in code-generated clients.
• Added guidance on avoiding 'additionalProperties: false' to ensure forward compatibility for objects.
• Clarified the impact of modern code generators (e.g., Quicktype) on schema-to-type validation.
• Updated the comprehensive capability schema example to align with these new extensibility rules.

Re: #244 (comment), 040684c

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing
  functionality to not work as expected, including removal of schema files
  or fields)
• Documentation update

---

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[raginpirate]

Good additions! This fills a real gap in the authoring guide.

However, are we missing the other half of the story here? This section covers additive changes (new fields, new enum values) and how to design schemas so they don't break clients. But it doesn't address subtractive/breaking changes (removing a field, retiring an enum value, tightening a type). We have a schema-transition mechanism in ucp-schema that covers this, and I think we might be able to port-over the guidance hiding in that repo here as just one or two extra paragraphs to tell the whole story here 😄

[gsmith85]

Hey @raginpirate, thanks for the feedback. You're absolutely right, this is only half the story 🙂.

I took a look at the transition logic in ucp-schema, and starting to pull it in but I actually decided to pause. Since we use date-based versioning, defining a lifecycle for subtractions (e.g. length of the migration window) may be a good idea and I think may require a bit more group deliberation.

I think the additive best practices are relatively uncontroversial. If you're game, I'll open a separate follow-up PR specifically for subtractions so we can align on a formal deprecation SLA without blocking.