Governance and licensing updates

[copiesofcopies]

Added governance documentation and updated licensing info.

[kriswest]

A few comments and questions.

[kriswest]

The 'approval' referred to is essentially review by the maintainers, who are supposed to try and apply a consensus-based decision from the SWG.

[copiesofcopies]

Correct.

[kriswest]

Languages changes @RexJaeschke recommends also need to be applied here, see:

• The Big Picture: Standard and Parts #482
• Part Sections and the Use of the Word “specification”  #483

[RexJaeschke]

Re the use of "S/specification," our current thinking is to use "Standard" and that "Specification" (uppercase) not be used. Kris has come up with new section names that eliminate such uses of. That said, we could revert to "Specification" instead, but should think that through a bit. Then there is the question of whether we should ever use "specification" (lowercase) anywhere regardless of the previous sentence outcome. The original confusion for me arose from the use of "Specification" in section headers, which suggested they were part of the requirements while other sections without that were not, simply because of the implicit understanding of what "Specification" means.

FWIW, ISO requires "Specification" rather than "Standard."

[kriswest]

@copiesofcopies I think I was still slightly off (I realised after reading @scooter99boston's clarification). Rather, our process is:

• various contributions are made by participants,
  • consensus (of the Standard Working Group) is checked (by the maintainers) on inclusion,
  • PRs are reviewed by an editor and maintainers then merged to our master branch
• Maintainers designated the master branch as a 'Pre-Draft' version of the standard
• That is then submitted back to the Standards working group for review and vote on adoption - which progresses it to the status of a Draft (4.3).
• We then do any work necessary to publish the standard, at which point it is published (4.4)

While writing this I spotted a further issue:

4.3. Working Group Approval. Once the Working Group believes it has achieved the objectives for its specification as described in the Scope,

I don't know what "the Scope" is or where it's defined as that document (from the Standards Project Blueprint) is not part of this PR. The scope is defined in the FDC3 Charter here: https://fdc3.finos.org/docs/fdc3-charter

Perhaps we should pull that content in to create the scope document OR refer out to it. If we're trying to head towards the full CSL I would suggest the former is the way to go. Do you agree?

[kriswest]

@copiesofcopies as its referred to, should we bring in the scope doc (from the Standards Project Blueprint) and populate with details from https://fdc3.finos.org/docs/fdc3-charter ?

Can you do that or should I raise a PR (into yours?) to do so?

[copiesofcopies]

Hi @kriswest thanks for catching this. I think it makes sense to include a scope file as you suggested. I've added a proposed scope to the pull request, incorporating the FDC3 mission (with minor changes to adapt it to the purpose) and scope (unchanged).

[kriswest]

Awesome, thanks @copiesofcopies.

I've raised a separate issue, #529, to cover adding a description of how we implement this governance to the README and website - hence I think this is now good to go!

[kriswest]

@copiesofcopies, @rikoe and I had a chance to discuss the proposed changes with @RexJaeschke who will be taking a closer look this week (and hopefully can advise on the correct language to use re: specification/standard).

One issue, in particular, we'd like to discuss further is section 4 in Governance.md '[Specification/Standard] Development Process'. What's described in that section is not a good match for the actual process we use, nor (we believe) a good match for any standard that is governed through a Git repository. It explicitly outlines a procedure that is problematic for us to implement. However, we'd like to stay inline with the procedures you will use for all standards projects (as deviation has caused us issues in the past), but believe you will have similar issues with any other standards projects using this approach.

4.1. Pre-Draft.** Any Participant may submit a proposed initial draft document as a candidate Draft Specification of the Working Group.

We think it very unlikely that someone will submit a complete draft of the standard, incorporating modifications. Rather, we ask that they raise an issue (a Github issue) outlining a proposal for changes to the standard. That is discussed by the Standards working group and the maintainers attempt to establish whether there is consensus that such a change should be implemented.

Assuming that there is consensus that the issue should be resolved, a PR is then raised by a Contributor or Maintainer to alter the standard. That PR is reviewed by the maintainers (and perhaps an Editor in future) - these reviews can be enforced via github project settings, but I think are not currently. PRs are also open to the rest of the community to review and comment - something that we could formalize as a specified minimum period of time (and protect with a github action) before it is merged. I currently highlight these at the SWG and other meetings to encourage review. A PR only contains edits to the files in the standard, rather than a full draft. There may will also be multiple PRs in flight at any one time. Github will force us to merge them one at a time and to resolve any conflicts between them.

When merged, that PR updates the current draft of the standard (the master branch of the repository). It is that draft (incorporating numerous different changes) that is presented to the SWG for 'Working Group Approval' (which can occasionally see it kicked by for further changes via new PRs) before it is finally adopted as the latest version of the standard. We've only had 3 such revisions for FDC3 so far (1.0, 1.1, 1.2).

Hence, I think it's section 4.1 (and perhaps 4.2) that needs to be reworked, possibly broken into multiple stages.

Finally, the 1.0 documents do define which parts of FDC3 are formally governed like this (the 4 specification documents) however, that has not been adequately defined since 1.1 and since then much of the content has moved into reference documents that were never formally defined as part of the standard or specification. We are about to change that (see #491) so that it will be easier to define in this document. Having that definition is important to the maintainers as it also frees us up from the governance procedures when we need to work on supporting material that is in the same repository, but not part of the standard, e.g. the NPM module, an implementations page, etc..

Should we discuss this verbally? Should we get the JDF to weigh in etc.?

[RexJaeschke]

Re to the definition of "Maintainers," "Editors," and "Participants," I have found it best to make them singular terms rather than plural. Although the difference here is not obvious, I have encountered situations in other specs in which the plural form can be ambiguous or needs more support to make it clear what a person of that rank is supposed to do. I have never had that problem with the singular form.

[scooter99boston]

To @kriswest's question, Contributions and PRs can be thought of as a ‘layer below’ pre-draft and draft materials. Contributors submit patches to various materials. These are Contributions. When the materials are ready to proceed to a Draft Specification, someone recommends the current work of Contributions to the Working Group for approval as a pre-Draft specification (under Section 4.1). At this point -- following the recommendation -- they are now a "Pre-Draft Document". When the Working Group approves them as a Draft Specification, these materials become a Draft Specification, and upon final approval... an Approved Specification.

[kriswest]

@scooter99boston thank you for the clarification - I'm comfortable that we don't need to change the Governance.md doc in that case. However, I'd like to include something in the FDC3 website and readme that outlines our implementation of the process and how a contribution makes it into a pre-draft.

We're about to propose, with help from @RexJaeschke, some additions (to the website - later to go into the standard itself within the website, but not into these documents) describing our versioning and deprecation policies + a proposed new experimental feature policy (exempts something from deprecation policy, provides notice that it may change rapidly). It would make sense (at least to me) to include this clarification on on how we implement this process with it.

Let me know if that does NOT make sense!

If that is correct, under this proposed governance document, then I'm happy to withdraw comments and approve it.

[kriswest]

LGTM

[kriswest]

Awesome, thanks @copiesofcopies.

I've raised a separate issue, #529, to cover adding a description of how we implement this governance to the README and website - hence I think this is now good to go!

[kriswest]

@ggeorgievx @donbasuno @mattjamieson please take a look at this PR when you can. We think it's now good to go.