CHARTER: Add WG proposal and templates #99
Conversation
Signed-off-by: Steve Winslow <[email protected]>
|
RFC @opencontainers/tob |
CHARTER.md
Outdated
| major revisions to existing OCI Specifications. Each OCI Working Group | ||
| shall have a defined scope of the OCI Working Group's intended activities | ||
| and goals. The end result of the OCI Working Group's work product shall be | ||
| either a new OCI Specification, an update to an existing OCI |
There was a problem hiding this comment.
I'm wondering if (akin to how when you read legal documents and they define terms at the beginning) we could describe clearly what the difference are between a new spec vs. a new project. Couldn't a new spec be a new project? What would be an example of a new spec that is not a new project, or a new project that does not have a new spec?
There was a problem hiding this comment.
Here are some examples I can think of:
- Update to an existing specification: add support for a new operating system to the runtime specification
- New specification: signatures for images and artifacts
- New project: reference implementation of a given specification
There was a problem hiding this comment.
These would be great to have! It would clear up any confusion that a working group is a specific project / task as opposed to a community.
There was a problem hiding this comment.
@vsoch and @samuelkarp Great suggestions -- in the first draft, I'd been treating "OCI Projects" as if it was a distinct and separate thing from OCI Specifications. But looking at the defined terms earlier in the charter, it looks like "OCI Projects" encapsulates OCI Specifications as well as implementations like runc.
In the updated commit, I've tried to clarify this by referring to e.g. "OCI Specifications and other OCI Projects", and added some of the clarifying examples that @samuelkarp suggested.
| TOB. The TOB will maintain a public list of all approved OCI Working | ||
| Groups. | ||
|
|
||
| - iv. Once an OCI Working Group determines that it has achieved its |
There was a problem hiding this comment.
This is a very formal, top down approach - which sort of makes sense to make an OCI project/spec official, but I think it might make it harder to come up with an idea, assemble a group of people that are interested in working on it, and then (after that organization and work is done) come back here. I'm wondering if, akin to CNCF, there can be one level down of an ability to define a group that is interested in a project, perhaps even get a space to work on it (if not under containers, maybe under oci-projects) and then go from there. What I think should be avoided is people wanting to work on something, having the motivation and energy to do so, but off the bat getting denied a working group / approval to include in OCI. It could be that it needs some work to foster additional thinking. It could also be that it needs some work, ultimately is not appropriate for OCI, but becomes a project or idea that many people find useful.
There was a problem hiding this comment.
Thanks @vsoch -- yes, I think this formal process in the charter is focused more on the stage at which a proposed group is far enough along to do a formal proposal to start a Working Group. For things that are more like experiments / initial testing, I think OCI could decide to create an "-experiments" or "-labs" or similar org, but I'm not sure that's something that needs to be explicitly called out in the charter.
| Groups. | ||
|
|
||
| - iv. Once an OCI Working Group determines that it has achieved its | ||
| objectives, the OCI Working Group leaders shall present to the TOB the |
There was a problem hiding this comment.
yeah, this almost sounds like it should happen at a later stage of this thinking / development process, but here's it's almost presented as the first thing you do, if that make sense. If there is no formal structure or organization for working on non-approved projects, perhaps some language could be added that makes a suggestion for how to go about it (e.g., mention channels of communication, suggestions for steps to go about it), and mentions that it's okay to take months, more than a year, to put together an idea / prototype / whatever is necessary to fully capture the project.
There was a problem hiding this comment.
Hmmm... I was thinking that this read more as saying that this would happen at the end of the drafting process (when the WG "determines that it has achieved its objectives"). At least that was my intent! Do you have a suggestion for a clearer way to phrase this?
There was a problem hiding this comment.
Maybe add a step before it to prompt to define objectives, channels of communication and (if appropriate) timelines? E.g., some WG might just be working on a text document, and others might want a toy implementation. Then leading into this section would follow nicely.
| approval the OCI Working Group may not describe it as a released OCI | ||
| Specification, and must designate it with a `-draft.#` suffix. | ||
|
|
||
| - vi. Following TOB approval of a draft specification to be released as an |
There was a problem hiding this comment.
The implication here is that someone that submits a draft that is approved becomes the maintainers (which is a commitment, so maybe it should be stated).
There was a problem hiding this comment.
That was not actually the point and I think could be called out better. The original idea is that the working group would have owners, and when a draft is approved and becomes a specification, the set of maintainers is voted on at that time as well. Becoming a maintainer is a commitment, but there should be no requirement that owners are also the maintainers. Owners are responsible for finding maintainers though before a draft could be approved as a new specification/project. I commented below about disambiguating owners and maintainers.
There was a problem hiding this comment.
@vsoch and @dmcgowan, good point. In the initial draft I hadn't fully appreciated some of the intended distinctions between owners and maintainers. In the follow-up commit I've rephrased some of the details here in the charter and in the WG governance documents. Take a look and let me know if you are good with the changes, or if there are other specific changes you'd like to see.
CHARTER.md
Outdated
|
|
||
| - vii. The TOB may, by a two-thirds vote, elect to disband an OCI Working | ||
| Group in its discretion, including if the TOB determines that the OCI | ||
| Working Group has not made meaningful progress or has become inactive. |
There was a problem hiding this comment.
"meaningful progress" could that be better defined? And inactive is easier, e.g., "no discussion or updates for X amount of time." Reading this I'd be afraid that my group would be disbanded pretty subjectively.
There was a problem hiding this comment.
These processes are always going to be subjective though with phrases like "in its discretion" or "meaningful". The idea behind any two-thirds vote is that it is the majority opinion. Whether the majority opinion is the right opinion is a different topic 😄
There was a problem hiding this comment.
I'd tend to agree with @dmcgowan here. The "meaningful progress" is given as an example, but not a limiting one, so ultimately it's the TOB's determination (by a supermajority 2/3 vote) whether to disband.
There was a problem hiding this comment.
Gotcha. Maybe when this is actual policy and this has happened a few times (if it even does) there could be examples of what is not meaningful progress. I think people tend to be busy on things (especially for extra obligations like a standards group) and would want to better understand what is not meaningful progress to avoid this event. Or give suggestions about positive behaviors, e.g.
- show up to weekly/monthly meetings to give a quick summary of progress
- have an active site that shows up to date meetings and activity
etc. etc. I think we would eventually just want this "scary case" of being disbanded and things to do to avoid it to be more concrete.
WG-TEMPLATE.md
Outdated
| ## Governance | ||
|
|
||
| * **Working Group**: | ||
| * The TOB is establishing the WG as an OCI Working Group, pursuant to section 6(p) of the OCI Charter. |
There was a problem hiding this comment.
| * The TOB is establishing the WG as an OCI Working Group, pursuant to section 6(p) of the OCI Charter. | |
| * The TOB is establishing the WG as an OCI Working Group, pursuant to [section 6(p)](https://github.com/opencontainers/tob/blob/master/CHARTER.md#6-technical-oversight-board-tob) of the OCI Charter. |
And note that section p is not in the current document, it's defined in this PR.
There was a problem hiding this comment.
Thank you! I've incorporated this in a couple of places in the follow-up commit.
WG-TEMPLATE.md
Outdated
| * Meetings of the WG shall be open to the public. | ||
| * Participants in the meetings shall comply with the [OCI Code of Conduct](https://github.com/opencontainers/.github/blob/master/CODE_OF_CONDUCT.md) and all other policies of OCI and The Linux Foundation. | ||
| * **TOB Approval**: | ||
| * The WG shall operate pursuant to the procedures set forth in section 6(p) of the OCI Charter, with regards to obtaining TOB approval for initial release of the work product and outputs as an OCI Specification or OCI Project, and for subsequent maintenance activities thereafter. |
There was a problem hiding this comment.
For these links to sections, I'm wondering if they should be smaller headings so we can link directly to them? if this is of interest I can PR to do this (and update the links here) after this is merged.
There was a problem hiding this comment.
That sounds like a good idea -- I'll defer to others but that sounds great to me.
WG-TEMPLATE.md
Outdated
|
|
||
| * **Working Group**: | ||
| * The TOB is establishing the WG as an OCI Working Group, pursuant to section 6(p) of the OCI Charter. | ||
| * **Maintainers**: |
There was a problem hiding this comment.
The charter section uses "owners" as term to represent this role. The owners of a working group are approved as part of the working group. I'm not sure I understand what "appoint" means in that context. Likewise, for making changes to a working group after it is approved, we should define the process as the owners request a change (in Amendments most likely). Any change requires the same level of approval as the initial proposal. It doesn't make sense to explicitly say that the TOB would remove or appoint new maintainers(/owners), the TOB would be responsible for either disbanding the working group or approving changes proposed by the owners, which could include changes to the owner or sponsor roles.
There was a problem hiding this comment.
Thanks @dmcgowan -- all good points and thanks for clarifying. I've tried to update in the follow-up commit and clarify the differences between "owners" and "maintainers". Grateful if you can take a look and see if this works for you, or if there are further clarifications that should be added.
CHARTER.md
Outdated
| major revisions to existing OCI Specifications. Each OCI Working Group | ||
| shall have a defined scope of the OCI Working Group's intended activities | ||
| and goals. The end result of the OCI Working Group's work product shall be | ||
| either a new OCI Specification, an update to an existing OCI |
There was a problem hiding this comment.
Here are some examples I can think of:
- Update to an existing specification: add support for a new operating system to the runtime specification
- New specification: signatures for images and artifacts
- New project: reference implementation of a given specification
WG-INFO.md
Outdated
| 1. a list of projects or organizations sponsoring the working group and | ||
| participating in the implementation and use case validation of the work done | ||
| by the group |
There was a problem hiding this comment.
Possibly: "a list of OCI Projects, non-OCI projects, or organizations"? This might help show that a WG working in the space of an existing OCI Project should cooperate with that project.
There was a problem hiding this comment.
Thanks! I've made updates along these lines in the follow-up commit to help clarify.
Signed-off-by: Steve Winslow <[email protected]>
|
|
||
| - i. The OCI may establish one or more working groups (each, an “OCI Working | ||
| Group”) to experiment, validate, and define new OCI Specifications or | ||
| major revisions to existing OCI Specifications. Each OCI Working Group |
There was a problem hiding this comment.
Suggest removing "major", from revisions. It's possible some capabilities may need a working group and may end up being a minor revision. The working group is formed to work out the details, to assure the revision is viable before adopting a change to the broad spec.
There was a problem hiding this comment.
Major is pretty important here IMO. Working groups aren't the only way to make progress, specs already have maintainers and a change process.
There was a problem hiding this comment.
If the goals of the working group are completely in scope for an existing major release version the spec (for example changes to current 1.0 specs), then the working group is not necessary and should work with existing maintainers. A major revision of a spec (say image-spec 2.0) or a new spec should be considered very similar from a process perspective, no compatibility requirements with previous spec versions and separate set of maintainers who focus on the released major spec version.
What could be missing here is features which span multiple existing specs. There could be a working group which expects smaller changes in existing specs but not necessarily a separate released version as a result. In those cases the working group is expected to have maintainers of those specs as sponsors and the working group is dependent on those minor revisions getting released. As asked below, a working group is not intended to work around maintainers of a released spec version to push through a feature. If that needs to be more clear, then we can make it clear. Removing "major" here would necessitate that in my opinion.
There was a problem hiding this comment.
The intent isn't to work around any process. Rather, there are questions that can only be answered through some iteration, incubation, and some sort of validation. The idea is to provide a means for innovation and let the result be reviewed for whether it should be incorporated into existing or new specs. At the beginning, the group may think it's simple to put in an existing spec. Or, it may be complex requiring a new spec. It's through the iteration, incubation, and validations that a proposal is formalized and likely pivots in some direction.
If the end result is known at the beginning, then we don't need a working group.
| - vii. The TOB may, by a two-thirds vote, approve requests from the owners | ||
| of an OCI Working Group to (a) amend the OCI Working Group's governance | ||
| document, or (b) adjust the composition of the owners or maintainers of | ||
| that OCI Working Group. The TOB may also, by a two-thirds vote, elect to |
There was a problem hiding this comment.
The TOB may, by a two-thirds vote, approve requests from the owners of an OCI Working Group to (a) amend the OCI Working Group's governance document, or (b) adjust the composition of the owners or maintainers of that OCI Working Group.
In most models, groups innovate in private and bring it forward only after the ideas has been formed and validated. The benefits is the group can operate with autonomy, but it's not public for others to have visibility or contribute. To create a working group under OCI, the group is already getting a lot more visibility (both good and bad). If the group has any concern the TOB will inject themselves into the group, it would likely discourage the process of working under the groups visibility. The TOB should have the right to disband a working group if it's non-functional or inactive. The group can ask for assistance, but being subject to intervention feels like overreach that will squash public innovation.
There was a problem hiding this comment.
The TOB should have the right to disband a working group if it's non-functional or inactive.
Can there be a more structured process for this? E.g., let's say people are really busy and the group is dormant for a bit - and then they get an email "sorry disbanded!" Maybe a warning would come first with structured questions about status and plan, and then follow up check in two weeks to re-assess? We want the TOB to be able to govern and control non-functional or inactive groups, but having the process (with kindness) will come across more as a supportive structure than an unexpected dictator.
There was a problem hiding this comment.
@vsoch agreed. By the time it may come to a vote, I would imagine there to have been some communication. I would not expect a consensus on a vote that hasn't been discussed or surfaced to the affected project
| * **Working Group**: | ||
| * The TOB is establishing the WG as an OCI Working Group, pursuant to [section 6(p)](https://github.com/opencontainers/tob/blob/master/CHARTER.md#6-technical-oversight-board-tob) of the OCI Charter. | ||
| * **Owners**: | ||
| * The WG proposal to the TOB will specify one or more initial "owners" of the WG. |
There was a problem hiding this comment.
Should we have a minimum of 2 or more owners? If something is to be run under OCI, seems it should be big enough, or interesting enough for multiple people to be engaged, to also assure the working group can scale to the needs of it being so visible under OCI.
There was a problem hiding this comment.
+1 here - from multiple organizations would be great too.
There was a problem hiding this comment.
Agreed, two or more from at least 2 organizations sounds good.
| major revisions to existing OCI Specifications. Each OCI Working Group | ||
| shall have a defined scope of the OCI Working Group's intended activities | ||
| and goals. The end result of the OCI Working Group's work product shall be | ||
| either: |
There was a problem hiding this comment.
This part is still a little unclear to me, when a WG is proposing changes to an existing specification that already has existing maintainers.
It seems like the following would be possible with this structure:
- a WG to form to make changes to an existing specification
- The WG decides on, and present these changes to the TOB for approval
- The TOB ratifies these changes
all without any input from the existing maintainers.
Would it make sense to handle the case where changes are being proposed to existing specification(s) separately from a brand new specification?
There was a problem hiding this comment.
I tried to answer that above, existing maintainers could be sponsors and existing specs could be dependencies, but not the final result of the working group. I think in the case you mentioned where the working group covers existing specs, the TOB would vote to disband the working group after all the existing specs are updated or the working group cannot make progress because their changes were not accepted by the maintainers.
| release of a new version of an OCI Specification, OCI shall notify all | ||
| Members as set forth in Section 8(d) of this Charter. | ||
|
|
||
| - vii. The TOB may, by a two-thirds vote, approve requests from the owners |
There was a problem hiding this comment.
nit: in iv above the term is "leaders" but here it's "owners"; we should use the same term in both places (whichever it is).
| of an OCI Working Group to (a) amend the OCI Working Group's governance | ||
| document, or (b) adjust the composition of the owners or maintainers of |
There was a problem hiding this comment.
nit: this is the first mention of a governance document for the working group. Do we need to specify that ahead of time?
| Working Group's owners and, where applicable following approval of a draft | ||
| as an OCI Specification, the Working Group's maintainers. | ||
|
|
||
| ## List of disbanded OCI Working Groups |
There was a problem hiding this comment.
nit: I think "former" might be less scary than "disbanded"
There was a problem hiding this comment.
Like @samuelkarp, a couple of nits that we can address, but this sets the basics for us to work with now.
LGTM
| Specification) or other draft project (to become an OCI Project) shall | ||
| require a two-thirds vote of the TOB. For a draft specification, prior to | ||
| such approval the OCI Working Group may not describe it as a released OCI | ||
| Specification, and must designate it with a `-draft.#` suffix. |
There was a problem hiding this comment.
like @swinslow comment, I wonder if these kinds of suffix can be grouped, or maybe have flexible language around how we explicitly designate that they are not-released/experimental?
| - vii. The TOB may, by a two-thirds vote, approve requests from the owners | ||
| of an OCI Working Group to (a) amend the OCI Working Group's governance | ||
| document, or (b) adjust the composition of the owners or maintainers of | ||
| that OCI Working Group. The TOB may also, by a two-thirds vote, elect to |
There was a problem hiding this comment.
@vsoch agreed. By the time it may come to a vote, I would imagine there to have been some communication. I would not expect a consensus on a vote that hasn't been discussed or surfaced to the affected project
There was a problem hiding this comment.
LGTM; looks like we are in good shape to get this finalized. I believe the actual implementation of a WG or two should expose any further clarifications that would be helpful and we are always free to make charter updates in the future if discrepancies are found in the implementation of the WG process.
|
@opencontainers/tob Can we take a look at this? |
| objectives, the OCI Working Group leaders shall present to the TOB the | ||
| draft specification or other project, along with such other information as | ||
| the TOB may require for evaluation of the draft specification or other | ||
| project. The TOB shall maintain a public list of such required information. |
There was a problem hiding this comment.
It seems like this public list is maintained at the bottom of WG-INFO.md, There's a few other places in this document which mention a "public list"; any chance we can make all these relevant links?
|
One comment about adding some context, but other than that it looks reasonable to me. (I'm not par of the opencontainers/tob github team, so I didn't get the previous pings; anyone know how to fix that?) |
|
6 LGTMs (and @tych0 is maybe? an LGTM) out of 9, so I think we can move ahead here. |
|
yep, if we want to add the links later that's fine. LGTM. |
|
Didn't we agree it would be re-drafted by LF legal in the last call (has that already happened -- I don't see a comment mentioning it?). I don't in principle have an issue with us merging it and ironing out any bugs in future revisions, but given that there isn't a drafting system for charter changes if we merge it now we're committing to this being the in-force charter until it gets re-drafted by legal. |
|
@caniszczyk @amye next steps? |
|
LGTMs 7/9 so this passes and can be merged Sam: #99 (review) FYI @swinslow is LF Legal and helped draft the changes @cyphar We can iterate on future modifications but this should unblock the creation of focused WGs |
(cc @caniszczyk)
This is a revised version of the OCI Working Group Draft Proposal for consideration by the TOB.
I've reworked the draft proposal somewhat, moving some details (such as lists of specific info that the TOB would require for review) into a separate
WG-INFO.mddocument. That way those pieces of information could be modified by the TOB in its discretion, without requiring a subsequent formal charter amendment.I've also made some proposed edits to the language of what remains in the charter portion, I'd encourage folks to please review closely. A minor note, I've also shifted the Working Group content into section 6(p) rather than as a new section 7, to avoid having to do lots of renumbering for the rest of the charter.
Finally, I'm including a
WG-TEMPLATE.mddocument which could be used by the TOB as a way to document the scope / work product and ways of working for each new WG, but the TOB could of course modify or omit this altogether if it doesn't like this approach.If the TOB does elect to proceed with adopting this, please note the procedure in section 12(a) of the OCI Charter for adopting charter amendments, including the required period of notice to members.
Signed-off-by: Steve Winslow [email protected]