IOPA Governance and Processes
How do you join a working group?
How do you make a formal request to change the standard. Who gets to make it?
How do you make an informal comment on the standard?
The platform (or combination of platforms) we use need to meet all of these requirements:
Present the standard publicly in a readable way.
A permanent link for a particular version of a standard and sections of it.
Somewhere where the working group and members of the public can discuss the standard informally.
Somewhere where the working group and members of the public can request to make formal changes to the standard.
A permanent history of changes made to the standard, who changed it and the rationale for the change.
Non-technical users (e.g. those without a background or experience in software development) should be able to take part in every step of the process.
The processes working group suggests using a combination of PubPub (standards.internetofproduction.org) and Discourse (community.internetofproduction.org) based on these criteria.
| Present standard
| Permanent link
| Informal discussion
|
Github | ✅ | ✅ | ✅ |
PubPub | ✅ | ✅ | ✅ |
Discourse | ✗ | ✗ | ✅ |
| Change suggestions
| Permanent history
| Non-technical
|
Github | ✅ | ✅ | ✗ |
PubPub | (partial) | (partial) | ✅ |
Discourse | (partial) | (partial) | ✅ |
Rough Notes:
Max’s notes on processes
Diffs? Do we need to have the ability to produce an actual diff between versions of the documents, or would a changelog document be sufficient? The latter are more easily human-readable
List of requirements that the standards development processes and platforms should meet
The ability to know who the originator of a proposal is and to have an archive of the responses t the proposal
The ability to link a proposal (where relevant) to the part of a published standard to which it applies
The ability to relate a section of the standard to the proposal(s) that contributed to it
The ability to apply the governance structure to the publishing of the standards
No implied knowledge of software development platforms or processes should be assumed on the part of any community members contributing to the process
There are a few options of how we handle public comments on PubPub.
We disable comments entirely.
We treat comments on PubPub as issues that need to be resolved.
Like 2 but we have a separate way of tracking all issues. Comments and other issues get added and marked as resolved there.
Comments on PubPub are open and are just that: comments.
If a comment is interesting and should be expanded members of the working group should point to the relevant forum section and ask the submitter to expand on it there.
Comments are never “archived” (removed from public view) unless they are unconstructive/abusive/spam.
Decision: Option 3
Change Proposal Process
Each standard has a channel on Discourse with a sub-channel for “Change Proposals”.
That channel is for change proposals only and has a specific template
Change Proposal posts are made as wiki posts
The voting plugin is enabled in this channel.
We use the “solved” Discourse plugin to mark change proposals as accepted, then the topic is closed. So there are three possible states:
Open
“Closed” + “Solved” = Accepted
“Closed” + nothing = Rejected
Potential Issues / Open Questions
WG/TF Meetings
Version Numbers
Option 1:
To make standard document version numbers less confusing with PubPub we suggest we adopt the following versioning scheme:
v1.1-en: The first version of the standard (in English). The PubPub URL will be:
v1.2-en: An amendment of v1 of the standard.
…
v2.1-en: The second version of the standard.
v2.2-en: An amendment of v2 of the standard.
…
The URL example-standard-v1-en
will re-direct the latest v1 release (in English). The URL example-standard-v2-en
will redirect to the latest v2 release (in English).
Translations
The standards are suffixed with ISO 639-1 language codes. For example, Somali translations would be:
Potential Issues:
“1.1” as a name for the first version of a standard breaks software versioning expectations
The name in the URL is not translated (is that a problem?)
Releases or translation releases may have smaller mistakes that require new releases causing the releases to no longer match up. (We can work around this by renaming pubs so the URLs get replaced.)
Option 2:
We stick to the semantic versioning we agreed on OKH.
v1.0.0-en: The first version of the standard (in English). The PubPub URL will be:example-standard-v1.0-en/releases/1
v1.0.1-en: A patch fix to the standard will be a new release of the Pub. The PubPub URL will be:example-standard-v1.0-en/releases/2
v1.1.0-en: An addition to the standard. It will be a new Pub. The PubPub URL will be:example-standard-v1.1-en/releases/1
v2.0.0-en: An addition to the standard. It will be a new Pub. The PubPub URL will be:example-standard-v2.0-en/releases/1
Potential Issues / Open Questions
Option 3:
We stick to the semantic versioning we agreed on OKH.
v1.0.0-en: The first version of the standard (in English). The PubPub URL will be:example-standard-v1-en/releases/1
v1.0.1-en: A patch fix to the standard will be a new release of the Pub. The PubPub URL will be:example-standard-v1-en/releases/2
v1.1.0-en: An addition to the standard. The PubPub URL will be:example-standard-v1-en/releases/3
v2.0.0-en: An addition to the standard. It will be a new Pub. The PubPub URL will be:example-standard-v2-en/releases/1
Potential Issues / Open Questions
If a new version of the English standard is released and any translations of the previous version are not simultaneously updated, we will need to ensure that we add an explanation at the beginning of the latest translated version that states that there is a more recent, untranslated, English version
Only a list of Pubs representing the Major versions (v1.0, v2.0, etc) of the standard can be generated. To see a non “0” minor version (e.g v 1.2), the visitor will have to go to the v2 Pub and use the PubPub “releases” drop-down to see the minor version. Note that PubPub doesn’t allow for releases to be named, so the minor versions would be “Release #<x>” in the drop-down.
Info Box
Version: 1.1.0
[iframe of plain html page with release history]
OKW Standard Release history
What we are doing on IOP-EC:
Wrote a “Statement of Purpose”
Review of existing industry standards and practices
(Identify stake-holders)
Stake-holder interviews (30 minutes unstructured)
recorded (with consent)
extract quotes
extract “key takeaways”
(Build prototypes)