[Doc] Binary Protocol Documentation is incomplete
- Dominant language
- Java
- Stars
- 15.3k
- Forks
- 3.8k
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 160
Description
### Search before asking
- [X] I searched in the [issues](https://github.com/apache/pulsar/issues) and found nothing similar.
### What issue do you find in Pulsar docs?
The [binary protocol specification documentation](https://pulsar.apache.org/docs/next/developing-binary-protocol/) is incomplete. For example, it does not cover in any great detail `RedeliverUnacknowledgedMessages` or transaction. This document should serve as the canonical description of all interactions with Pulsar brokers.
### What is your suggestion?
I would suggest the following approach to resolve the issue:
1. Define a MVP for documenting a protocol command:
1. Textual description of command
2. Tabular description of all attributes, including defaults, value validations, example values, and textual description
3. Enumeration of key use-cases that involve the command
4. Description of each use case with corresponding sequence diagram showing client-broker interaction
2. Audit [current documentation](https://pulsar.apache.org/docs/next/developing-binary-protocol/) with respect to the aforementioned MVP to understand existing documentation coverage.
3. Audit [protobuf binary protocol](https://github.com/apache/pulsar/blob/master/pulsar-common/src/main/proto/PulsarApi.proto) to help understand undocumented commands.
4. Create issues for each under/un-documented command to create relevant documentation for said command.
5. Work on each created issue.
### Any reference?
_No response_
### Are you willing to submit a PR?
- [X] I'm willing to submit a PR!
Contributor guide
Research direction
Start with the current binary protocol documentation at developing-binary-protocol and compare it with pulsar-common/src/main/proto/PulsarApi.proto. Define the proposed MVP for documenting commands, audit current coverage and undocumented interactions such as RedeliverUnacknowledgedMessages and transactions, then create focused follow-up issues; done means the audit and issue breakdown are complete.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100