What's needed?
There was a lot of work put to think about how to build good, safe and reliable wrappers from protobuf messages, resilient to malformed data and forward-compatibility. We need to make sure this acquired knowledge doesn't get lost.
Proposed solution
Go through all the changes between v0.4.0 and the current head and look for patterns and conventions, weighting latest changes more than early changes when there are conflicting patterns, as some things even changed during this development cycle.
Create a new contributing guide that compiles all the learnings here and translate them to good, actionable wrapping guidelines developers can use to create new wrappers, without having to think about all the trade-offs.
Additional context
The current CONTRIBUTING.md focuses on more environmental stuff, so it might make more sense to add this guide elsewhere, probably directly in docs/.
In terms of documentation organization, we can use https://github.com/frequenz-floss/frequenz-channels-python/ (mainly) and https://github.com/frequenz-floss/frequenz-sdk-python/ as examples. But this project probably needs 3 different user guides, depending on the target audience:
- End user guide (for indirect users, users of frequenz-client-* projects, should probably only use the wrappers surface)
- Client developer guide (for implementors of frequenz-client-* projects, should probably use wrappers, protobuf conversion functions, and create their own wrappers for protobuf messages that are not part of frequenz-api-common)
- Contributor developer guide (for people contributing to this library)
So the guide proposed here should target 2 and 3. 3 might have other information that is only specific to this common library, so maybe we can make this guide its own section, a 4th guide, as it should be general guidance, like "Protobuf wrapping guide" or similar.
What's needed?
There was a lot of work put to think about how to build good, safe and reliable wrappers from protobuf messages, resilient to malformed data and forward-compatibility. We need to make sure this acquired knowledge doesn't get lost.
Proposed solution
Go through all the changes between v0.4.0 and the current head and look for patterns and conventions, weighting latest changes more than early changes when there are conflicting patterns, as some things even changed during this development cycle.
Create a new contributing guide that compiles all the learnings here and translate them to good, actionable wrapping guidelines developers can use to create new wrappers, without having to think about all the trade-offs.
Additional context
The current
CONTRIBUTING.mdfocuses on more environmental stuff, so it might make more sense to add this guide elsewhere, probably directly indocs/.In terms of documentation organization, we can use https://github.com/frequenz-floss/frequenz-channels-python/ (mainly) and https://github.com/frequenz-floss/frequenz-sdk-python/ as examples. But this project probably needs 3 different user guides, depending on the target audience:
So the guide proposed here should target 2 and 3. 3 might have other information that is only specific to this common library, so maybe we can make this guide its own section, a 4th guide, as it should be general guidance, like "Protobuf wrapping guide" or similar.