From bb50d437e912106fa576b3f889bd28d64e0652b8 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Tue, 25 Feb 2025 10:08:52 +0100 Subject: [PATCH 1/2] style guide: no requirements in "Examples" sections --- style-guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/style-guide.md b/style-guide.md index 5820af5091..bff24a1967 100644 --- a/style-guide.md +++ b/style-guide.md @@ -21,6 +21,7 @@ The following additional rules should be followed but currently are not enforced 9. Use [Oxford commas](https://en.wikipedia.org/wiki/Serial_comma), avoid [Shatner commas](https://www.latimes.com/archives/blogs/jacket-copy/story/2011-06-30/goodbye-oxford-comma-hello-shatner-comma). 10. Use `` for link anchors. The `` format has been deprecated. 11. Headings use [title case](https://en.wikipedia.org/wiki/Title_case) and are followed by a blank line. +12. Do not add requirements in "Examples" sections, and avoid [RFC2119 key words (MUST, MAY, ...)](https://datatracker.ietf.org/doc/html/rfc2119) in these sections. Plus some suggestions, rather than rules: From 4ffcb64ecd89c14360ef0c2cb891c2abb69e22b3 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 28 Feb 2025 09:22:52 +0100 Subject: [PATCH 2/2] Update style-guide.md @lornajane's suggestion --- style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style-guide.md b/style-guide.md index bff24a1967..8d4bf7139d 100644 --- a/style-guide.md +++ b/style-guide.md @@ -21,7 +21,7 @@ The following additional rules should be followed but currently are not enforced 9. Use [Oxford commas](https://en.wikipedia.org/wiki/Serial_comma), avoid [Shatner commas](https://www.latimes.com/archives/blogs/jacket-copy/story/2011-06-30/goodbye-oxford-comma-hello-shatner-comma). 10. Use `` for link anchors. The `` format has been deprecated. 11. Headings use [title case](https://en.wikipedia.org/wiki/Title_case) and are followed by a blank line. -12. Do not add requirements in "Examples" sections, and avoid [RFC2119 key words (MUST, MAY, ...)](https://datatracker.ietf.org/doc/html/rfc2119) in these sections. +12. Do not use [RFC2119 key words (MUST, MAY, ...)](https://datatracker.ietf.org/doc/html/rfc2119) in "Examples" sections or when explaining examples, and state requirements only in sections that are clearly normative. Plus some suggestions, rather than rules: