otto-de / otto-de/api-guidelines
[new rule] must provide compatibility mode for produced messages
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 50
- Forks
- 16
- PR merge metrics
- No merged PRs in 30d
Description
(i) This issue has been manually transferred from a former internal repository, as a private repository issue cannot be transferred to a public repository.
Context
Messages may evolve over time. In order to signal a consumer what a compatible change is, the compatibility mode must be documented for produced messages.
The following modes exist:
| Mode | Changes allowed | Compatible against | Description |
|---|---|---|---|
| FORWARD | - Add fields - Delete optional fields |
previous version | Older clients can read events written with the next newer schema. |
| FORWARD_TRANSITIVE | see FORWARD | all previous versions | Older clients can read events written with all newer schemas. |
| FULL | - Add optional fields - Delete optional fields |
previous version | Older clients can read events written with the next newer schema. Newer clients can read events written with the previous schema version. |
| FULL_TRANSITIVE | see FULL | all previous version | Older clients can read events written with a newer schema. Newer client can read events written with all previous schema versions. |
Other common modes such as backward and none should not be allowed, as they break existing clients.
Analyze if exemptions can be made to this rule if all consumers are prepared for a breaking change.
Reference
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing the existing API guidelines and the linked AsyncAPI and Confluent Schema Registry references. Define where the produced-message compatibility rule belongs, which modes it permits, and how consumer-prepared exemptions should be evaluated; done means the rule and its exemption criteria are documented consistently.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100