Skip to main content
SearchLoginLogin or Signup

Processes Notes

Published onMay 12, 2022
Processes Notes
·

IOPA Governance and Processes

  • How do you join a working group?

    • Processes WG suggestions:

      • All meetings are announced on the forum, newsletter and website in advance.

      • Members of the public are invited to audit all meetings.

      • Members of the public may ask to formally join the working group at any time.

      • How to join meetings and ask to join is prominently displayed on all web properties (main website, PubPub and discourse).

  • How do you make a formal request to change the standard. Who gets to make it?

    • Processes WG suggestions:

      • All formal change proposals are made through the relevant change proposal category on the forum (e.g. the “IOP-OKH Change Proposals” category).

      • A template/format suggestion is loaded when you create a new topic in that category.

      • Any member of the public can join the forum and make a formal change proposal.

      • Example of a change proposal

  • How do you make an informal comment on the standard?

    • Processes WG suggestion:

      • You can leave informal comments on PubPub or on the relevant category on the forum (e.g. the “Open Know-How” or “Open Know-Where” category).

  • How do you decide to make a change to the standard? (accept / reject a proposal)

    • Based on discussions with the OKH working group we suggest:

      1. A change proposal is made on the forum.

      2. The change proposal is raised at a WG meeting.

      3. Ideally full consensus is achieved within the WG, i.e. everyone agrees.

      4. Chair of the WG decides how to reconcile diverging opinions if they arise. If full consensus is not possible then the WG chair decides how decision is going to be made; usually this means chunking the proposal down into smaller ones that allow for a reasonable decision.

      5. If this does not reconcile all disputes then the chair decides how to make the decision. E.g. votes, i.e. majority wins and the minority that disagrees may create a hard fork of the standard.

      • If accepted: add a post on the forum thread that says “This was accepted to the … version of the standard. <link>” and marking this as the “answer” to the proposal.

      • If rejected: add a reply explaining the rejection and “close” the thread.

  • What do votes on a change proposal on the forum mean?

    • Just an indicator of popularity.


Standards Platform Requirements

The platform (or combination of platforms) we use need to meet all of these requirements:

  1. Present the standard publicly in a readable way.

  2. A permanent link for a particular version of a standard and sections of it.

  3. Somewhere where the working group and members of the public can discuss the standard informally.

  4. Somewhere where the working group and members of the public can request to make formal changes to the standard.

  5. A permanent history of changes made to the standard, who changed it and the rationale for the change.

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


  1. Present standard

  1. Permanent link

  1. Informal discussion

Github

PubPub

Discourse


  1. Change suggestions

  1. Permanent history

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

PubPub Comments

There are a few options of how we handle public comments on PubPub.

  1. We disable comments entirely.

    • Commenting on the standard should be done through Discourse.

    • You can still use perma-links to specific sections on the forum.

  2. We treat comments on PubPub as issues that need to be resolved.

    • When they are resolved we “archive” the comment.

  3. Like 2 but we have a separate way of tracking all issues. Comments and other issues get added and marked as resolved there.

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

    • Voting replaces “likes”

    • Any forum member can vote but the votes have no official meaning

    • The working group can gauge the popularity of a proposal from votes

  • We use the “solved” Discourse plugin to mark change proposals as accepted, then the topic is closed. So there are three possible states:

    1. Open

    2. “Closed” + “Solved” = Accepted

    3. “Closed” + nothing = Rejected

Potential Issues / Open Questions

  • What about forks/drafts of the documents?

    • Dependency on governance process for a particular standard (ie. how decisions are made, and by whom, on which proposals are approved)

  • What about PubPub comments (see above)?

WG/TF Meetings

  • Discourse tags to be used for each WG / TF:

    • Agendas (rolling?) to be set up for each one

    • Calendar

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:

    • example-standard-v1-en/releases/1

  • v1.2-en: An amendment of v1 of the standard.

    • example-standard-v1-en/releases/2

  • v2.1-en: The second version of the standard.

    • example-standard-v2-en/releases/1

  • v2.2-en: An amendment of v2 of the standard.

    • example-standard-v2-en/releases/2

The URL example-standard-v1-en will re-direct the latest v1 release (in English). The URL example-standard-v2-enwill 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:

  • v1.1-so: The Somali translation of the first version of the standard. The PubPub URL will be:

    • example-standard-v1-so/releases/1

  • v1.2-so: The translation of the amendment of v1 of the standard.

    • example-standard-v1-so/releases/2

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

  • A list of Pubs can be generated with all Pubs containing Major and Minor versions

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

Related Links:

  • W3C Process documentation: https://www.w3.org/2021/Process-20211102/

What we are doing on IOP-EC:

  1. Wrote a “Statement of Purpose”

  2. Review of existing industry standards and practices

  3. (Identify stake-holders)

  4. Stake-holder interviews (30 minutes unstructured)

    • recorded (with consent)

    • extract quotes

    • extract “key takeaways”

  5. (Build prototypes)

Forum rules:

  • Max, Ronald and standard working group members will be given moderator privileges of the relevant channels.

Forum things to test:

  • What happens if a user deletes an account?

  • Can we have a public section where only “members of the working group” can post?

  • Can we customise the “solved” plugins to our needs? What plan do we need for that?

  • Single sign-on between discourse and PubPub not possible

  • Tiered participation?

  • Todo

    • Releases plain html page Github repo

    • MW: explore topic templates instead of wizard

    • MW: Set up “custom wizard” plugin for Change Proposal submissions

      • Form fields:

        • Proposer* : the name / email of the proposer

        • Title* : short title that describes the proposal

        • Current wording: optional text field that contains the wording in the standard that the proposal is proposing to change

        • Permalink to relevant section: permalink from pubpub

        • Proposal* : text detailing the content that is proposed to be amended / added / deleted from the standard

        • Motivation* :

        • Risks :

      • Should it be via the forum, or somewhere else for “triage” before adding to the forum?

    • MW: Set up translator plugin

      • Set up Azure service but plugin config isn’t showing up on Discourse

    • Set up “Docs” plugin

      • Need to determine “docs” categories

      • Wait until we have some docs to publish?

    • Evaluate Events vs Calendar plugin

    • OAuth

      • Linked In

      • MS (not so easy for Discourse)

      • Github

      • Twitter

      • Google

      • Facebook

    • Set up SPF for email config: https://controlpanel.communiteq.com/cp/iopalliance/email

Comments
0
comment

No comments here

Why not start the discussion?