Patch release process (fixes without changing meta-schema or test compliance) and branch usage

[handrews]

Goals

• To keep draft/2020-12 as the current designated meta-schema and test compliance target by refreshing the IETF draft document before or very soon after the current set's expiration on June 11, 2021.
• To be more responsive to feedback while also demonstrating stability. The community should not have to wait another year-plus for non-controversial clarifications and corrections that do not change compliance requirements.
• To have a more flexible process for working on large and small things simultaneously. In particular, it might be easier for new contributors to get involved on a patch release without having to worry about the larger debates. Things like focusing on better wording often get starved for attention compared to keyword changes.

[EDIT: A past example of this was the draft-handrews-*-01 specifications, which were still draft-07 just like draft-handrews-*-00 were. This made for a clearer IETF document but most people probably didn't even notice unless they'd paid close attention to draft-handrews-*-00. Most people just look at the latest draft and what meta-schema it lists, and then talk about the meta-schema. This is explained in detail on the specification links page.]

Proposal

• Create a draft-next branch for the larger changes, and make it the default target.
• Allow patch PRs to either master or a draft-patch branch (I'd lean towards master for now as our PR volume isn't that high).
• Add a draft-patch milestone (alongside the existing draft-next milestone) and use it to manage release contents.

The rule for a patch release would be: If in doubt, leave it out!

Patch release PR criteria

• MUST NOT require a meta-schema change (the meta-schema bugfix process is an independent process / discussion)
• MUST NOT require a test suite change (unless there's clear consensus that the test suite was outright wrong due to spec ambiguity)
• MAY involve adding a test case for a previously ambiguous and uncovered area
• SHOULD NOT "clarify" ambiguities if a clear de-facto consensus has already emerged on a different interpretation. In such cases, the clarification would be felt as a change. There is some gray area here, although we could adjust this point in either direction.

Patch release process criteria

Changes MUST NOT draw objections from @json-schema-org/core-team (or @json-schema-org/collaborators ? I think we need to clarify what these are which will be a different community discussion). The goal is straightforward minor improvements, with things needing discussion moving out to draft-next. They can be moved back to the patch release if things get resolved.

Patch release examples

• Fix typos/errors (even if this appears to change functionality- that time we reversed exclusiveMaximum and exclusiveMinimum comes to mind, as no one really thought that's what compliance required)
• Streamline wording or conceptual models without changing implementation requirements
• Add non-controversial examples
• Add CREFs soliciting input
• Clarify ambiguity (subject to the restrictions above about de-facto standard interpretations)

---

If we can get a tentative consensus ASAP on creating a draft-next branch and rebasing most open PRs to that immediately, that will preserve our options without having to do git surgery. The only post-draft-2020-12 commit is a wording improvement for type, which is clearly a patch-level change.

We can then sort out this process, even if we ultimately abandon it and merge the branch back, without pressure on the decision.

[karenetheridge]

Just to clarify, you are proposing creating a new draft/2021-XX, and also the creation of new metaschema documents to accompany it, but it (the metaschemas) should be identical (save for identifying URIs) as draft2020-12?

[handrews]

Good question - thanks! The answer is no, there would be nothing done with meta-schemas at all, and the URIs would stay the same. Just like draft-handrews-*-00 and draft-handrews-*-01 were both draft-07, used literally the same meta-schema files and URIs, and were mostly just a blip in people's awareness. But draft-handrews-*-01 was substantially more clear in several places.

You can see how we presented this in the specification links.

[handrews]

Actually this part of the spec links page covers it better: http://json-schema.org/specification-links.html#understanding-draft-names-and-numbers

[jdesrosiers]

I think this is a good idea and something we should do for all draft releases going forward.

[Relequestual]

I would agree!

[gregsdennis]

I agree with this.

Is this process itself something that would need mentioning in the specification anywhere?

[handrews]

Nope, although it will be clear from the changelog. [Here's how we handled the last patch release](This draft is purely a clarification with no functional changes) (we did say "This draft is purely a clarification with no functional changes" but we did not say anything about process. It worked just fine last time, we just didn't formalize the idea. And then what was intended to be a patch release after 2019-09 got big (probably my fault- I recall some "cleanups" that got out of hand) and became 2020-12, so I figure we should be intentional this time.

[handrews]

While I don't consider this proposal formally accepted (@Relequestual what is the process for determining that?), I think there's enough buy-in (with no objections) to warrant setting up the branch and re-targeting PRs as appropriate. We can always merge it all back down so that is 100% reversible, while keeping our options open on the patch release.

[Relequestual]

I think for Discussions, unless anyone proposes anything different, we operate as we otherwise would, looking for general consensus and acting accordingly.

This Discussion is approaching 14 days. We haven't given it much publicity, but I don't think this is of much general interest. More interest to those actively working on the spec.

If this is successful, I feel this approach should become our established release pattern.

[handrews]

Given @Relequestual's comment about it having been 14 days 7 days ago, I'm declaring this accepted after 21 days without objection.

idk what we're doing for persistent process documentation now- I had forgotten that we actually have some on the spec repo wiki although I have not checked to see if any of it is still accurate.

[Relequestual]

Have I ever mentioned I can't stand repo wikis and I'd love to turn them all off and make any useful content more visible?

[Relequestual]

IMHO, this is the sort of decision that should be documented as an ADR per #15
Let me enable Issues for this repo and we can track that the decision needs to be made memorialized.
The decision, as with all decisions, are not immortal, and can be superseeded. The records are immuteable.

[Relequestual]

@handrews Hey buddy. You still want to take lead on this effort? Otherwise, I'm happy to step in after API Spec Conf 2021.

[Relequestual]

I'm taking this on.