Style guide / release checklist for the specification

[handrews]

As I write PRs, I keep finding little things that I'm not sure how to do. Some examples:

• What are the rules about which headings go in the TOC and which don't?
• It seems clear that RFCs are to be written without a space between the "RFC" and the number; are there other conventions to follow?
• RFC references often go to a specific section without noting that section in the text, is that intentional or should we be more explicit in the readable text? I think some do mention section numbers or titles, but I have no idea what's ideal
• RFC references use a mix of URLs, some pointing to "old-style" text-ish formatted renderings, some to modern renderings
• Section title capitalization - it seems like we go full title-case, but it would be a good idea to document it
• When referencing a named Object, does it need to always link to the section or only on first mention in a given paragraph / section whatever?
• Similarly, when referencing an RFC multiple times in a section, does every mention need to be a link?
• We should document that we use REQUIRED but not OPTIONAL as came up in a recent PR. Unless we want to follow issue editorial: field not explicitly required can be considered optional #2470 and start using OPTIONAL - we should either do that or close editorial: field not explicitly required can be considered optional #2470
• How do we handle informative vs normative references? (see also issue Add appendix "Informative references" to published spec documents #3740)

There are other things with less impact (e.g. for bulleted lists do we treat bullet points as sentences or not?), but these are the ones that I hit the most.

[lornajane]

• If I had to guess, the TOC hasn't been well-maintained and we should probably regenerate that.
• I don't really want to go back and update the RFC references but good practice is probably to cite the section as well in the link test.
• Title case is fine and we need to improve our markdown automation anyway. Let's document it for now (I know how you feel about our not-contributing file, but maybe let's add a section for style and then we can clean up around it)
• I do not feel it would improve anything for our users if we start explicitly putting OPTIONAL everywhere so I'd like the "just document that we don't do it that way" option, please!

[handrews]

Thanks @lornajane – yeah I don't think we need to go update every RFC citation, but in some areas where I'm already doing PRs that are thick with them, knowing how to handle references to different sections, some of which happen multiple times, would be really helpful.

I'm totally fine with documenting things in the not-contributing file, I've just realized that I'm over capacity and can't take on rewriting that right now even when I'm the person pushing for changes / documented policies :-/ At some point, if no one else steps up, I'll get back to it, but that's multiple months out right now.

[handrews]

Some pre-release checklist items

• re-generate TOC
  • consistent section titling
  • consistent linking
  • update links for GitHub changes done on main
  • make links to appendices B-E work in respec rendering
• Adjust "front matter" of published specs
  • What is our authoritative spec URL and how do people find it? #3576
• make RFC links consistent
  • rfc-editor.org vs datatracker.ietf.org
  • different anchor styles (auto-id vs section numbers vs ???)
  • link to sections (always, sometimes, never?) (Preserve section links in ReSpec output #3863)
    • section link style: "section x.y" vs "§ x.y" (RFCs seem to use the first style)
• Add appendix "Informative references" to published spec documents #3740 (informative references)
• update version numbering policy now that we are more-or-less back to SemVer?
• Release notes, Blog post
  • explain how to interpret apparently-but-not-actually-new MUST/SHOULD/MAY/etc.
• Publish latest schemas after closing Define and document our schema publishing process #3715
• Add links to latest schemas to https://spec.openapis.org/ landing page because the new patch versions point there

  a non-authoritative JSON Schema based on this document is also provided on spec.openapis.org for informational purposes

Plus some "maybes":

• Inconsistent usage of quotes in yaml examples #1720
• Usage of field vs property #2660

[lornajane]

This is a really great list, that I think we should be expanding to make into a "do it this way" list of style guide directives/tips. We can just keep editing your previous comment and then publish when we're done?

[handrews]

Something that's important to keep in mind for a style guide / release checklist:

• When writing PRs to add new content, the important thing is to get the content in, particularly if the PR is coming from someone who knows more about the area than anyone else available. At this stage the style is not important. If we have a style guide, we can reference that, but do not kill PRs or discourage contributors with endless revisions that area a matter of opinion or stylistic preference.
• After the PRs for a release are in, other people should go over the whole thing for consistency and tone. Those are different skills than are involved in just getting the content in. It's also important, and too-often neglected, but you cannot do this step until you have all of the content and are sure that your style/tone changes are applied consistently throughout. Never mix these steps!

[handrews]

We also now have numerous issues about updating this or that reference that really need to be governed by a policy and not ad-hoc discussions:

• draft-bhutton-json-schema-00 is deprecated , Should the specification point to the 01 ? #3934
• RFC 7231 has been obsoleted by RFC 9110 #3800
• YAML JSON Schema is not enough for roundtrip-safe #2951

[ralfhandl]

Maybe add

• Avoid the deprecated <a name=... and instead use <span id=..., placing the link target text inside the <span> element

[lornajane]

I ticked off the items about the table of contents since we no longer need that. And I suggest that the versioning wording is something that covers all our needs and unless there's a big problem we identify with it, it shouldn't be a high priority for taking our time and energy.