Communication & Deprecation Policy
This document describes how Swapcard communicates API changes to Content API and Analytics API consumers, and the lifecycle for deprecating and removing fields, queries, and mutations.
1. Scope
This policy applies to:
- Content API (Developer schema) — documented at swapcard.dev/content-api
- Analytics API — documented at swapcard.dev/analytics-api
It covers any change that affects the public contract of these APIs: field removals, type changes, behavioral changes, query/mutation removals, and enum value changes.
2. Principles
- Backward compatibility by default — All schema changes are backward compatible. New fields, new optional arguments, and new types are non-breaking and can be shipped freely.
- No silent removals — A field or query will never be removed without going through the full deprecation lifecycle.
- Migration path required — Every deprecation includes a concrete alternative or migration instruction.
- Communicate early, communicate often — You will learn about deprecations through multiple channels and have ample time to migrate.
3. Change Categories
Non-Breaking Changes (no deprecation required)
- Adding a new field to an existing type
- Adding a new query or mutation
- Adding a new optional argument to an existing query/mutation
- Adding a new enum value
- Adding a new type, union, or interface
These changes are documented in the changelog but do not require a deprecation notice or migration period.
Deprecations (standard lifecycle)
- Marking a field, query, or mutation for future removal
- Replacing a field with a new alternative (e.g.,
attendees→withEvent.attendees) - Phasing out an enum value
These follow the Deprecation Lifecycle defined in Section 5.
Breaking Changes (require deprecation lifecycle)
- Removing a field, query, or mutation
- Changing a field's return type
- Making a nullable field non-nullable (or vice versa for inputs)
- Changing an enum value's meaning
- Changing the behavior of a resolver in a way that would break existing consumers
Breaking changes are only allowed after the full deprecation lifecycle has been completed.
4. Communication Channels
Every API change is communicated through the following channels:
| Channel | When | What |
|---|---|---|
| Changelog | Every release | All changes (additions, deprecations, removals) are documented in the relevant changelog: Content API Changelog or Analytics API Changelog |
| Deprecation + reminders | Sent to all mailing list subscribers at each phase of the deprecation lifecycle | |
| Schema directive | At deprecation | The @deprecated(reason: "...") directive is added to the field in the GraphQL schema, visible in introspection and developer tooling |
5. Deprecation Lifecycle
The standard deprecation lifecycle spans 12 months from announcement to removal.
| Phase | Timeline | Technical Action | Communication |
|---|---|---|---|
| Announcement | Day 0 | @deprecated directive added to the field with migration instructions. Documented in changelog. | Email to all mailing list subscribers with deprecation details and migration guide. |
| First reminder | Month 3 | No technical change. | Reminder email highlighting the upcoming removal and migration instructions. |
| Second reminder | Month 6 | No technical change. | Reminder email. If usage analytics are available, usage data may be included to help you assess urgency. |
| End of Life | Month 12 | Field/query/mutation removed from the schema. Changelog updated. | Final email confirming the removal, with a link to the migration guide. |
Timeline extensions: If usage analytics show significant ongoing usage of a deprecated field at Month 6, Swapcard may extend the lifecycle beyond 12 months with additional reminders. Extensions are communicated in the changelog and via email.
6. Emergency Deprecation (Fast-Track)
In exceptional circumstances, a shorter deprecation period may apply:
| Reason | Minimum Notice | Process |
|---|---|---|
| Security vulnerability | 30 days | Direct outreach to known consumers + email to mailing list + changelog entry. Removal after 30 days. |
| Legal / compliance requirement | 30 days | Same as security. If the legal requirement mandates immediate removal, the field is removed immediately with post-hoc notification. |
| Critical bug in deprecated field | 30 days | If a bug is found in an already-deprecated field and fixing it would require significant effort, removal may be accelerated to 30 days with direct outreach. |
Emergency deprecations are documented with a clear justification in the changelog.
7. Migration Requirements
Every deprecation includes the following:
- Deprecation reason — A clear
@deprecated(reason: "...")message in the schema explaining why the field is being removed. - Alternative — The replacement field, query, or approach. For example:
"Use withEvent.attendees instead". - Migration guide — A changelog entry (or linked document) with before/after code examples showing how to migrate.
- Timeline — The planned removal date (12 months from announcement unless fast-tracked).
Example deprecation message format:
@deprecated(reason: "Use withEvent.attendees instead. Will be removed on 2027-03-01.")
8. Summary
| Change Type | Deprecation Required? | Notice Period |
|---|---|---|
| New field / query / mutation | No | None (ship freely) |
| Field removal / type change | Yes | 12 months |
| Security / legal removal | Yes (fast-track) | 30 days minimum |
| Enum value removal | Yes | 12 months |
| Behavioral change | Yes | 12 months |