Complete the new version of the Spec

[benjagm]

Problem: The scope the of next specification release is distributed among different issues and PRs. Some of the items have been included in milestones but not all what makes it difficult to progress with the release discussions. By identifying the pending scope and applying some project management to support the progress we hope to lighten the whole process.

Team working on this issue:

• @benjagm to project manage this work.
• @jdesrosiers and @gregdennis to write up list of work the believe still needs to be done.

Assessed as high impact/high effort during our collaborators summit 2023.

Updated plan:

• We'll create a new milestone called stable-release. We'll create a project board to enhance collaboration and transparency.
  Milestone: https://github.com/json-schema-org/json-schema-spec/milestone/10
  Project Board: https://github.com/orgs/json-schema-org/projects/15/views/1
• We'll conduct a grooming session to setup the initial spec backlog associating the issues with the new milestone.
• We'll decide if we remove the existing milestones.
• We'll decide a labelling system to identify the issues' workflow. Before, during and after an issue is added to the spec scope.
• We'll run 1 week cycles to decide the issues to focus on during that cycle. 1 session at the beginning to decide scope of the cycle and 1 session at the end to review the closed issues, and decide the issues for the next cycle. Short cycles can be done in during the OCWM.

[gregsdennis]

I plan on bringing this up in the call next week, there are a lot of open questions that need answering before we can consider starting actual work on the spec again.

• We have to align on our definition of compatibility: https://github.com/orgs/json-schema-org/discussions/404
• I think with the last call we decided we'll do a stable URI + release URIs for meta-schemas. ✔️
• We need to restart the SDLC discussions.
• We need to decide whether we'll assign URIs to keywords: URI naming scheme for user/one-off/non-standard keywords json-schema-spec#1401 & Add keyword id to output unit json-schema-spec#1065
• Are we extracting output from the core spec? Extract output to a separate specification json-schema-spec#1320 & Gregsdennis/output spec json-schema-spec#1385
• We need to decide on how we're going to edit the document. Convert the spec to Markdown json-schema-spec#1335, Convert the spec to Markdown json-schema-spec#1357, & Convert to Markdown json-schema-spec#1412

And those are just from the collection of tabs I keep open in my browser. There are definitely more in the issues and discussions lists. One of these should probably be a prune/clean of those lists.

[gregsdennis]

Ideally, I'd like this to be more than just a couple of guys writing the spec. I'd like to get wider input, but that input only seems to come when we post specific issues in public forums. Even then, the comments we do get are generally loosely tangential rather than helpful.

[jdesrosiers]

Here's a list of things I had in mind before things went off the rails, https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aissue+is%3Aopen+label%3Asdlc

These are the main issues I think need we need to resolve before we can really dive into spec changes.

• How are new features added and evolved (and possibly removed)?
  1. Staged stability process
  2. External extension specifications
  3. Add, deprecate, remove
• What features will be included in the first release?
  1. 2020-12
  2. 2020-12 + new keywords
  3. Some subset of 2020-12
  4. draft-07
  5. 2020-12 limited to what is compatible with draft-07

Here's a lightly ogranized and incomplete survey of discussions, issues, PRs, and ADRs related to the next release.

• IETF Decoupling
  • Convert the spec to Markdown json-schema-spec#1357
  • Convert to Markdown json-schema-spec#1412
• Foundations
  • What kind of changes will be allowed and when
    • https://github.com/orgs/json-schema-org/discussions/404
    • https://github.com/orgs/json-schema-org/discussions/282
    • https://github.com/orgs/json-schema-org/discussions/234
    • Add PROCESS.md documenting the new SDLC json-schema-spec#1348
    • https://github.com/json-schema-org/json-schema-spec/blob/main/adr/2022-11-stable-spec.md
  • Supporting forward compatibility
    • Unknown keywords
      • https://github.com/orgs/json-schema-org/discussions/241
      • https://github.com/orgs/json-schema-org/discussions/329
      • Specify a naming scheme for non-assertion keywords json-schema-spec#1399
  • https://github.com/orgs/json-schema-org/discussions/204
• Keywords
  • RequireAllExcept - Add requireAllExcept keyword json-schema-spec#1144
  • DynamicRef
    • Remove initial resolution - Drop the initial resolve step for dynamic references json-schema-spec#1142
    • Remove bookending - Remove bookending requirement for dynamicRef json-schema-spec#1139
• Dialects
  • Should there be a default dialect? https://github.com/orgs/json-schema-org/discussions/405
  • Require explicit dialect
    • https://github.com/orgs/json-schema-org/discussions/190
    • Put boundaries on lack of "$schema" behavior json-schema-spec#1353
• Vocabularies
  • Remove optional vocabularies? https://github.com/orgs/json-schema-org/discussions/342
• Media Type
  • IANA registration https://github.com/orgs/json-schema-org/discussions/198
  • Should we decouple JSON Schema the language (not format specific) from JSON Schema the media-type (coupled to JSON)?

json-schema-org/json-schema-spec#1420
json-schema-org/json-schema-spec#1421

[gregsdennis]

I think we should probably do a complete "compatibility" survey of the text describing each feature. @jdesrosiers brought up a good point regarding JSON pointers that cross schema resource boundaries being defined but not required. Things like this could come back to haunt us.

[benjagm]

Thanks @gregsdennis and @jdesrosiers.

I found that most of the issues you added in your lists are not part of the milestones future/next. Shall we start by having a session to triage and add them to the milestone?

[benjagm]

Started this discussion in Slack:

• What is the difference between the milestones draft-next and draft-future in the spec repo?
• Who can add an issue to the milestone?
• What is the difference between draft-next and draft-future and what is the milestone associated to the next release of the spec.
• Who can label issues in the spec repo?
• Do we have documented the labels purpose? Are the labels associated to the spec development process?

I think is important to be clarified in order to start the collaboration the best way.

[jdesrosiers]

Those milestones are not part of any process we've been following. I, for one, haven't used them at all. My guess is that someone (probably Henry, maybe Ben) created them a long time ago as a personal organization process and no one has looked at them since.

In any case, so much has changed since those milestones were created that I'm sure they have no meaning anymore. They were created before we decided to move to a stable spec process, which changes everything. I suggest we throw out those milestones and start fresh. The first thing we should do is decide how we want to track spec progress. If we want to use milestones, let's start a new one, but if we want to use something else, that's fine too.

[Relequestual]

Those milestones are not part of any process we've been following. I, for one, haven't used them at all. My guess is that someone (probably Henry, maybe Ben) created them a long time ago as a personal organization process and no one has looked at them since.

Yeah, confirming this. And agree with everything else Jason said above.

[benjagm]

My suggestion to operate is:

1. We'll delete those milestones to discontinue the IETF "draft" naming convention. The issues will remain open without associated milestone.
2. We'll create a new milestone called next-version or anything else.
3. We'll associate the issues identified by Greg and Jason in this discussion with that new milestone.
4. We'll review if those issues are enough to ensure a stable release or we need to add more.
5. We'll conduct a grooming session to setup the spec backlog.
6. We run 8 weeks cycles to decide issues to focus on during that cycle. 1 session at the beginning to decide scope of the cycle and 1 session at the end to review the closed issues, and decide the issues for the next cycle.

[jdesrosiers]

@benjagm Sounds like a plan! Let's get started.

1. We'll delete those milestones to discontinue the IETF "draft" naming convention. The issues will remain open without associated milestone.

I suggest we leave those milestones in place until the first grooming session. That will give us a chance to review them in case there's something important in there. We can delete them after that first session.

2. We'll create a new milestone called next-version or anything else.

I suggest stable-release.

3. We'll associate the issues identified by Greg and Jason in this discussion with that new milestone.

Not all of those issues are necessarily going to go into the milestone. For example, some are new or modified keywords and it's very possible that we decide that we aren't going to add/change anything that isn't necessary for stable release.

4. We'll review if those issues are enough to ensure a stable release or we need to add more.

They're definitely not. I expect there will be very few issues initially and once those are resolved, we'll be in a better position to fill out backlog more representative of what it will take to get the release done.

5. We'll conduct a grooming session to setup the spec backlog.

Let's do this ASAP.

6. We run 8 weeks cycles to decide issues to focus on during that cycle. 1 session at the beginning to decide scope of the cycle and 1 session at the end to review the closed issues, and decide the issues for the next cycle.

I prefer much shorter cycles. We could even go as short as 1 week. With cycles that short, reviewing and deciding issues for the next cycle would be short enough to be part of the weekly OCWM.

[benjagm]

Thanks for the great feedback @jdesrosiers . I like your proposals quite a lot.

This is the updated plan after incorporating @jdesrosiers suggestions:

1. We'll create a new milestone called stable-release. We'll create a project board to enhance collaboration and transparency.
2. We'll conduct a grooming session to setup the initial spec backlog associating the issues with the new milestone.
3. We'll decide if we remove the existing milestones.
4. We'll decide a labelling system to identify the issues' workflow. Before, during and after an issue is added to the spec scope.
5. We'll run 1 week cycles to decide the issues to focus on during that cycle. 1 session at the beginning to decide scope of the cycle and 1 session at the end to review the closed issues, and decide the issues for the next cycle. Short cycles can be done in during the OCWM.

[benjagm]

I have created the milestone: https://github.com/json-schema-org/json-schema-spec/milestone/10
And I have created the Project Board: https://github.com/orgs/json-schema-org/projects/15/views/1

[benjagm]

I'll suggest to conduct the 1st grooming session to setup the backlog in the next OCWM session (2023-07-24). I already added this point to the agenda: #450

[gregsdennis]

Do we still need this issue? We have a board now.