HIP-1037 - Protocol Buffer Specification #1037
Conversation
✅ Deploy Preview for hedera-hips ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
jsync-swirlds
force-pushed
the
hip-protobuf-specification
branch
from
8a09bb9
to
ee64753
Compare
jsync-swirlds
changed the title
jsync-swirlds
force-pushed
the
hip-protobuf-specification
branch
4 times, most recently
from
cfbe260
to
87d5e01
Compare
jsync-swirlds
force-pushed
the
hip-protobuf-specification
branch
from
a70f7ff
to
23d9432
Compare
jsync-swirlds
force-pushed
the
hip-protobuf-specification
branch
3 times, most recently
from
0585d46
to
b3aec6d
Compare
jsync-swirlds
force-pushed
the
hip-protobuf-specification
branch
from
b3aec6d
to
312456d
Compare
Nana-EC
requested review from
netopyr,
steven-sheehy,
jasperpotts,
poulok,
SimiHunjan and
Nana-EC
| Hedera APIs so that I can confidently design my application to call those | ||
| APIs. | ||
| - As an independent implementor I want to have clear and accurate specification | ||
| for all Hedera APIs so that I can design an independent, correct, and |
There was a problem hiding this comment.
Do we plan to rename them to "Hiero APIs" or something similar?
There was a problem hiding this comment.
Not sure. Definitely something to consider.
There was a problem hiding this comment.
Yeah but I don't believe in this PR or in this repo.
Changes will probably be done at once by @mgarbs in the heiro org I imagine
jsync-swirlds
force-pushed
the
hip-protobuf-specification
branch
from
312456d
to
2ef32fc
Compare
| ## Content Guidelines | ||
| ### General `proto` File Guidelines | ||
| - Protocol buffers are compiled for the `hedera-services` codebase using a | ||
| custom processor 'PBJ'. While no other entity is required to use `PBJ`, all |
There was a problem hiding this comment.
Hmm, is this essentially enforcing the community to have a comfortable understanding of PBJ outputs. This may be true but do we want to require this?
Should we call out the practical implications here so users know if they are compatible. How can they have confidence, does it require ensuring certain reserved types aren't used or does it require passing some tests on PBJ?
There was a problem hiding this comment.
The simplest way is to pass the PBJ integration test, or pass compilation in the hedera-services codebase. Probably we need to, when resources permit, split the PBJ integration test out into a useable compatibility test library for general use.
The hedera-services repo is already the primary repository for any proto under the services subfolder (hedera-protobufs is a manually maintained copy), and the current direction is to continue to split every group of proto files out to the various code repositories (so Block Node would have block stream; mirror node would have MN their files, etc...).
Ideally, PBJ should compile anything that protoc would. There are a decent array of open bugs and limitations that prevent this, however. PBJ is also behind protoc standard by a bit. PBJ supports proto3 while protoc (with the new "editions" versioning) is at the 2023 Edition.
There was a problem hiding this comment.
I've added some explanation to describe the recommended current process.
* Initial proposed HIP text Signed-off-by: Joseph Sinclair <[email protected]> Update hip-1037.md to Review Signed-off-by: Michael Garber <[email protected]>
- Added style guidelines as an asset. - Linked these guidelines in the specification section - Moved the large PR link to the reference implementation section - Added reference to protoc-gen-doc - Added two rejected ideas - Added paragraph breaks in two places - Updated style guidelines to mention PBJ and Map field concerns. - Adjusted style guidelines to add section headings and clarify the examples. Signed-off-by: Joseph Sinclair <[email protected]>
- Added some additional sample content - Clarified "equivalent" types with respect to these guidelines - Clarified line break usage - Clarified when a horizontal rule (`<hr>`) tag is appropriate - Added additional clarification for paragraph breaks - Added guideline for non-API comments using "line oriented" (`//`) style comments. - Added a user story related to smart contract requirements. Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
force-pushed
the
hip-protobuf-specification
branch
from
024c656
to
eea1903
Compare
This pull request introduces HIP-1037, titled "Protocol Buffer API Specification" The proposal aims to enhance the Hedera API declarations by adding detailed API specification text to every protocol buffer element. This API specification text is added in a manner very similar to the Java API specification by adding properly formatted comments above each API message and field. The standard protoc plugin protoc-gen-doc processes these comments, in combination with an included template, to produce markdown files that fully detail the API.