Open Community Working Meeting 2022-10-31 - 14:00 PT

[Relequestual]

📺 See Recording

⏪ Go To Previous Meeting

Agenda

Topic	Owner	Decision/NextSteps
Where to include deprecated features? Deprecation of keywords. Semantic or numbered stage names?	@jdesrosiers	Read the details Semantic or numbered naming of stages rolled over
General governance of project	@handrews	Adopt a governance model

Highlights

• All items on agenda excluding one were discussed.
• Excluded item from the agenda was semantic or numbered naming of stages.
• With respect to place of residence for deprecated features and keywords, it was agreed upon that a few document structure should be tried.
• Which of the two i.e documentation or specification should be terse and explanatory.
• Is specification the place for guidance or the documentation ?

Actions

• A governance model is to be made and adopted
• Contact OpenJS Foundation regarding Licensing and Governance
• Select a person to act as the point of contact with OpenJS Foundation regarding governance onboarding
• Discuss and resolve the pending SDLC issues

Attendees

Account
@jdesrosiers
@Julian
@jviotti
@handrews

Details

Governance of Specification Development

As the working group is transitioning from discussion about specification development to development of the specification. The working group memebers would want a formal governance process in place to make the development of specification smoother.

What should a governance model provide for ?

• A formal conflict resolution process to resolve deadlocked viewpoints without reliance on individual's interpersonal skills.
  • External input on disputed point of views and more were argued for, without particulars agreed upon as of now.
• Clarity on legal aspects.
• Clarity on licensing aspects.
• How to avoid things that may be in contributors' blindspot, here external input could be of help.
  • The point is to have more people involved but not just to checkoff boxes by covering every industry the goal is rather to reach a deterministic specification and problems are brought to light early on in the process thereby making for an efficient functioning of SDLC.
• Provide a mechanism to have the ability to do nothing on a deadlock as well. eg. Members felt that decoupling from IETF's consensus process could have had better resolution mechanism.

The list above is not exhaustive

Which governance model to adopt ? and oversight mechanism ?

A governance process already in existence in other specification/standard development processes (eg. OpenAPI, AsyncAPI) can be used to pick parts from. That is, adopt a model already in use at other projects of similar size/scope and adapt it to the JSON Schema's needs. Members also decided to seek OpenJS foundation's help with respect to governance alongwith assigning a person to be point of contact with them for future communication.

Moreover, the members feel that @Relequestual is most well suited to undertake governance but has a lot on his plate and a solution is to be found if he is to be asked to undertake goverance.

Further relevant reading material on governance can be found here

---

Unresolved SDLC issues

Deprecation of features

A few methods were touched upon eg. hidden by default, jump to deprecated sections etc. The basic philosophy agreed upon is of making deprecated stuff to be seeked out rather than always/accidentely visible i.e deprecated things are demphasized. Members agreed that a few ways can be tried without much overhead, as restructuring documents is easy. One of them can then be decided upon depending its suitability.

Concept of deprecating keywords

Should there be the concept of deprecating keywords if they are never removed ? As it is understood that predictable and deterministic output is the aim of specification, a possible solution members touched upon was of allowing implementers to not support older releases that have deprecated features in it. eg. A implementer may provide support for only 2023 and up only. This combined with the usual phasing out a feature from announcement of deprecation to deprecation with release cycles.

Ancillary discussions from the above

Which document is best suited to provide guidance?

Is spec the place for guidance or the documentation ? Does the specification need to be the as terse as possible ? An example shared in the meeting was of http specification. The members felt they have the option of having specification, documentation, blogs etc. as compared to http specification which traditionally has been terse and in a single place. The discussion is currently not settled and ongoing.

Where does the clarification of specification reside?

The members do not want the test suite to play the clarfication role for specification. Therefore, should documentation serve specification clarification role ? But if clarification is not in the normatively written specification what would it mean to be in compliance with a specification. Members argue that a balance is to be maintained between clarfication and normatively defined specifics. eg. How much URI specification is explained in the specification and alongside its usage and clarification in documentation.

Specification therefore can be then thought of as how, what and why a specific was decided upon and is. Whereas, a documentation is for usage. The discussion is currently ongoing and is unsettled.

---

Further Reading

• Benchmarking Governance ISO 37000 - the first ever international benchmark for good governance
• Governance of Organizations
  • ISO 37000:2021 Governance of organizations — Guidance
  • ISO 37000:2021(en) Governance of organizations — Guidance
• OpenAPI How to Contribute-Governance
• AsyncAPI Technical Steering Committee-TSC
• Julian's Twtich Channel

[handrews]

I would like to discuss governance for the project. As seen by the many recent spec issues filed with the sdlc label, we are about to move into a more active phase of spec work.

Not all of those issues were actually decided to that level of detail in the SDLC discussion. For some of those topics, we have at least three highly divergent proposals from various regular contributors.

In addition to needing process for resolving intractable disagreements, we need to ensure that we are including voices from outside of the regular contributor group on major decisions in general. There is also the concern of disparity in available time between the full-timers and the volunteers that can make it easy to miss input on important decisions.

I know that @Relequestual has been doing some work in this area, but there are many things on his plate. What is our plan for putting appropriate governance in place? Do we need assistance in order to do so in a timely manner? What resources are available to help us do this?

[jdesrosiers]

These are the last topics that came up in the SDLC proposal we haven't come to a decision on yet.

• Should deprecated features be included directly in the spec or someplace else?
• Should we deprecate keywords at all if we don't plan to ever remove them?
• Should we use semantic names rather than numbered stages?

[benjagm]

Closing this issue as all tasks are completed. Thanks for your contributions!