search

json-schema-org / community

A space to discuss community and organisational related things
81 stars 33 forks source link

Complete the new version of the Spec #415

Open benjagm opened 1 year ago

benjagm commented 1 year ago

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:

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

Updated plan:

gregsdennis commented 1 year ago

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.

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 commented 1 year ago

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 commented 1 year ago

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.

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

https://github.com/json-schema-org/json-schema-spec/issues/1420 https://github.com/json-schema-org/json-schema-spec/issues/1421

gregsdennis commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

Started this discussion in Slack:

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

jdesrosiers commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

@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.

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

I suggest stable-release.

  1. 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.

  1. 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.

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

Let's do this ASAP.

  1. 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 commented 1 year ago

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 commented 11 months ago

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 commented 11 months ago

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