Skip to content
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

Merged
merged 3 commits into from Sep 24, 2021
Merged

Finalize the HIL Design TRD #2828

merged 3 commits into from Sep 24, 2021

Conversation

phil-levis
Copy link
Contributor

@phil-levis phil-levis commented Sep 17, 2021

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

  • Updated the relevant files in /docs, or no updates are required.

Formatting

  • Ran make prepush.

@hudson-ayers
Copy link
Contributor

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.

@lschuermann
Copy link
Member

that will not break any existing documentation

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.

@hudson-ayers
Copy link
Contributor

that will not break any existing documentation

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.

@phil-levis
Copy link
Contributor Author

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.

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).

hudson-ayers
hudson-ayers previously approved these changes Sep 20, 2021
bradjc
bradjc previously approved these changes Sep 21, 2021
ppannuto
ppannuto previously approved these changes Sep 21, 2021
talking about the return types of split-phase operations.
@phil-levis
Copy link
Contributor Author

Did a final detailed editing pass, and added a note about cancel operations.

@phil-levis
Copy link
Contributor Author

bors r+

@bors
Copy link
Contributor

bors bot commented Sep 24, 2021

@bors bors bot merged commit 3b5bffe into master Sep 24, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants