Link to Eventing Data Plane Contract/SPEC
- Dominant language
- HTML
- Stars
- 5.1k
- Forks
- 1.3k
- PR merge metrics
- No merged PRs in 30d
Description
**Describe the change you'd like to see**
Speaking to many function authors (i.e. Knative Service with Eventing), especially newcomers, most of them are not aware of the underlying data plane contract, e.g. used by `brokers`. This can lead to issues where retry and error behavior by a function (`Kservice`) is incorrectly assumed/handled.
Examples [`SPEC`](https://github.com/knative/specs/blob/main/specs/eventing/data-plane.md#event-acknowledgement-and-delivery-retry) says to retry on `404` which is typically not what users expect (`404`s are usually not retriable and the SPEC bends the rules here IMHO a bit for a particular use case).
**Proposal:** add a section to the docs describing the impact of the data plane contract to Knative function authors so at least they are aware of the behavior. The only issue is that not all implementations might strictly follow the SPEC, so this should be considered best effort/best practice for now until we are sure that all implementations strictly follow the SPEC.
**Additional context**
Add any other context or screenshots about the feature request here.
Contributor guide
Research direction
Start by reading the linked Eventing Data Plane SPEC, especially its event acknowledgement and delivery retry section, then locate the function-author documentation area where this guidance belongs. Add a section explaining the contract's retry and error behavior, including that implementations may vary, and verify that the result clearly communicates best-practice expectations to newcomers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kubernetes
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100