New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Finalize the HIL Design TRD #2828
Conversation
It seems a little odd to treat this TRD the same as other TRDs (like say, TRD104). If our understanding of how to best write HILs evolves over time, it seems that we should still be allowed to add new guidelines to this document -- that will not break any existing documentation, and because this doc does not specify any software interfaces, will not break any users of any interface either. |
I'm not sure whether that is the case. Once we start saying something as "This TRD is in compliance with TRD $HIL_TRD_NUM." in other TRDs, this might well be problematic. Having the HIL TRD be subject to the same strict rules regarding deprecation and being superseded by another TRD means that these references in the other TRDs still resolve to the proper document. It'll prevent a domino effect of an entire subtree of inter-documentation references be inconsistent. |
Yeah, I agree that modifying existing rules seems bad, but if we could specify an append-only policy for this document I don't think that could break anything, and seems preferable to having to start a new TRD or deprecate this one anytime someone thinks of another useful guideline. Though I suppose the process for finalizing individual new rules would be unclear. |
The model for this is something like RFC 2581. Of course, thinking might evolve. This could lead to subsequent TRDs that add more principles, or obsoleting this one, or explaining one of them in greater detail due to subtleties we discover. You see this in 2581, which was both amended and then later obsoleted. It's worth noting this TRD doesn't have any MUST statements (which is intentional). |
talking about the return types of split-phase operations.
3f8c258
Did a final detailed editing pass, and added a note about cancel operations. |
bors r+ |
Pull Request Overview
This pull request finalizes the HIL design TRD as TRD2 (since it is a Best Common Practice). It's been in the repository for over three months without edits or major changes. This is partially motivated by the need to reference this TRD in other ones (e.g., say something like "this follows Rule X of the HIL Design TRD...").
Testing Strategy
N/A
TODO or Help Wanted
This pull request still needs a detailed read-through and proof-checking, as well as "speak now or forever hold your peace" concerns.
Documentation Updated
/docs
, or no updates are required.Formatting
make prepush
.