You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2022/08/24 09:33:59 UTC

[GitHub] [pulsar] teabot opened a new issue, #17258: [Doc] Binary Protocol Documentation is incomplete

teabot opened a new issue, #17258:
URL: https://github.com/apache/pulsar/issues/17258

   ### 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!


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] michaeljmarshall commented on issue #17258: [Doc] Binary Protocol Documentation is incomplete

Posted by GitBox <gi...@apache.org>.
michaeljmarshall commented on issue #17258:
URL: https://github.com/apache/pulsar/issues/17258#issuecomment-1226313503

   @teabot - thanks for creating this issue. I've noticed the same short comings, and I agree that a review of the existing spec would be very valuable. I'd be happy to help work on this or to review any resulting documentation.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


[GitHub] [pulsar] github-actions[bot] commented on issue #17258: [Doc] Binary Protocol Documentation is incomplete

Posted by GitBox <gi...@apache.org>.
github-actions[bot] commented on issue #17258:
URL: https://github.com/apache/pulsar/issues/17258#issuecomment-1256835637

   The issue had no activity for 30 days, mark with Stale label.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [I] [Doc] Binary Protocol Documentation is incomplete [pulsar]

Posted by "merlimat (via GitHub)" <gi...@apache.org>.
merlimat commented on issue #17258:
URL: https://github.com/apache/pulsar/issues/17258#issuecomment-6377130769

   Thanks @teabot. The website docs live in apache/pulsar-site, and the binary protocol page there still covers only a subset of the commands in PulsarApi.proto (for example, no transaction commands). I'm moving this issue there so the audit you proposed can be tracked with the page.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org