community icon indicating copy to clipboard operation
community copied to clipboard

Published 20 hours ago • verified publisher icon json-schema-org

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

Open Relequestual opened this issue 1 year ago • 2 comments

📺 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

  • [x] A governance model is to be made and adopted
  • [x] Contact OpenJS Foundation regarding Licensing and Governance
  • [x] 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

Relequestual avatar Oct 27 '22 12:10 Relequestual