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

style guide: no requirements in "Examples" sections #4382

Merged
merged 2 commits into from
Mar 2, 2025

Conversation

ralfhandl
Copy link
Contributor

@ralfhandl ralfhandl commented Feb 25, 2025

Follow-up to #4339 (comment).

PR #4339 added text to an "Examples" section that used requirements language with "MUST" and "MAY". In this case the text was just copied verbatim from "non-example" sections of the spec, and no new requirements were added.

Better style is to

  • not to add requirements in a section called "Examples" or similar because readers may be confused whether these are really normative requirements or just explanations to the examples
  • not to use requirements language in explanations to examples

Tick one of the following options:

  • schema changes are included in this pull request
  • schema changes are needed for this pull request but not done yet
  • no schema changes are needed for this pull request

@ralfhandl ralfhandl added the editorial Wording and stylistic issues label Feb 25, 2025
@ralfhandl ralfhandl requested review from a team as code owners February 25, 2025 09:10
@lornajane
Copy link
Contributor

I tried to follow the thread of the other pull request, some comments, and what caused this change, but I'm not really clear, sorry. Could you add a note to the pull request description about what problem this solves or what we need to do or not do? I think it would help to inform the reviewer (me!)

@ralfhandl ralfhandl requested review from lornajane and a team February 28, 2025 08:23
Copy link
Contributor

@lornajane lornajane left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update and the description, feel much more confident that I know what I'm approving this time!

@lornajane lornajane merged commit 3e40ee4 into main Mar 2, 2025
4 checks passed
@lornajane lornajane deleted the ralfhandl-style-guide-no-requirements branch March 2, 2025 20:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
editorial Wording and stylistic issues
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants