apache / apache/pulsar

[Doc] Binary Protocol Documentation is incomplete

Open
#17,258 2 comments 2 reactions 0 assignees View on GitHub
doc-required Stale
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.