openbmc.lists.ozlabs.org archive mirror
 help / color / mirror / Atom feed
* OTP-5: "OpenBMC TOF Proposal" Process
@ 2021-10-21  4:33 Patrick Williams
  2021-10-21  4:47 ` Patrick Williams
                   ` (2 more replies)
  0 siblings, 3 replies; 7+ messages in thread
From: Patrick Williams @ 2021-10-21  4:33 UTC (permalink / raw)
  To: OpenBMC List

[-- Attachment #1: Type: text/plain, Size: 7143 bytes --]

As I mentioned in https://lore.kernel.org/openbmc/YXDrQAf73igsbu7+@heinlein/,
the TOF needs a process for making proposals.  We have a bit of a cycle though
in that we need a proposal for the process but we don't have a process for
proposals.  So, this email is a proposal for the process for making proposals
with which I am attempting to follow the proposed proposal process.

Before I get into the proposal itself, the proposal proposes how the community
should interact with proposals.  I propose that we all follow said
proposal(s):

    Any member of the OpenBMC community may give feedback by:

    1. Expressing a vote to the top post of the Github issue.
    2. Providing grammatical suggestions to the Gerrit commit.
    3. Responding on the mailing list with opinions on non-grammatical OTP content.
    4. (Least desirable) Providing off-line feedback to a TOF member(s).

    Community members should refrain from:

    1. Voting on any comment in the Github issues beyond the top post.
    2. Cluttering the mailing list discussion with grammatical suggestions.

Now for the full contents of the proposal:

-------------------------------------------------------------------------------

---
OTP: 5
Title: "OpenBMC TOF Proposal" process
Author: Patrick Williams <patrick@stwcx.xyz>
Create: 2021-10-20
Type: Process
Requires: N/A
Replaces: N/A
Superseded-By: N/A
---

# OTP-5: "OpenBMC TOF Proposal" Process

## Background

When the [TOF Contract][1] was written it outlined using Github Issues to track
"requests for process or technical changes, or solicitations for the opinion of
the TOF" but did not give any guidelines on how this is to be accomplished.  In
the process of discussing the [first proposal][2], the overall feeling of the
TOF was that the process needed to be better defined in order to codify the
expected process and to ensure community feedback was appropriately solicited.
This is that process.

## Definitions

* OTP: An "OpenBMC TOF Proposal".  Any request to the TOF should be framed as
  an OTP as documented by this process.

* Author: The individual(s) who write the initial draft of the OTP.

* Champion: A member of the TOF, confirmed by the current TOF chair, who will
  work with the Author while this process is being followed to ensure that
  appropriate updates to the OTP are being made.  If the Author is a member of
  the TOF it is expected that they will also act as Champion to their own OTP.

## Process

An OTP works through three (3) states on the way to adoption: Draft, Discussion,
Final.  During the Draft state, the responsibility lies on the Author to ensure
the OTP is able to move further in the process.  As the OTP enters Discussion
state it is the responsibility of the current TOF chair to find a member of the
TOF to act as Champion to move the document along further in the process.  The
Author and Champion will work together to make changes to the proposal as might
be necessary as it moves to Final state (unless it is rejected earlier in the
process).

### Draft State

Draft state is when the Author creates the initial proposal.  Any member of the
OpenBMC community may create OTPs by doing the following:

1. Creating an issue in the [repository][3] with a title and no contents.
    a. The issue number assigned by Github will become the OTP number for this
       proposal.

2. Use the OTP template for the proposal type to write a draft proposal and send
   a copy to the [OpenBMC mailing list][4] with the title "OTP-N: Title" and the
   contents being the filled-in OTP template.

3. Add a comment to the issue with the link to the mailing list archive entry on
   [lore.kernel.org][5].

4. Create a Gerrit commit to the docs repository with the OTP template
   contents named `tof/proposals/otp-N.md` (along with any corresponding changes
   elsewhere in the docs repository that might be necessary to enact the OTP).

Once all of these are accomplished, the OTP enters Discussion state.

### Discussion State

Any member of the OpenBMC community may give feedback by:

1. Expressing a vote to the top post of the Github issue.
2. Providing grammatical suggestions to the Gerrit commit.
3. Responding on the mailing list with opinions on non-grammatical OTP content.
4. (Least desirable) Providing off-line feedback to a TOF member(s).

Community members should refrain from:

1. Voting on any comment in the Github issues beyond the top post.
2. Cluttering the mailing list discussion with grammatical suggestions.

An OTP will remain in Discussion state for the timeline expressed in the [TOF
contract][1] with respect to issue voting.  TOF members will vote by reacting
to the OTP Github issue's comment containing the mailing list archive.

An OTP will exit Discussion state when one of the following occurs:
1. The OTP is rejected due to the voting rules contained in the TOF contract.
2. The OTP is accepted due to the voting rules contained in the TOF contract.
3. The OTP is discussed at a regular TOF meeting and is either rejected,
   partially accepted, or fully accepted.

If the OTP is fully or partially accepted, the chair will confirm a Champion to
move the issue through Final state.

### Final State

The purpose of the Final state is to get the OTP wording finalized into
languages that matches the intent and spirit of what the TOF accepted.  If the
OTP was automatically accepted without discussion, this might be as simple as
fixing minor grammatical issue.  If the OTP was partially accepted by the TOF
this may require rewriting large portions of the OTP to match the intention of
the TOF.  The Champion is suppose to represent the TOF's viewpoint to ensure
that the Author and Champion can formulate the final wording for the OTP.

When the Champion believes the Gerrit commit adequately represents what the TOF
had approved, they should comment as such on the commit and inform the TOF
members via Discord.  TOF members will then have 48 hours to review the final
wording and either approve or reject the commit in Gerrit as having met the
intention of the previous TOF vote.  An approval (or rejection) does not mean
that the TOF member agrees (or disagrees) with the proposal, but that the TOF
member believes the final wording matches the previous TOF agreement(s).  Thus,
a TOF member should reject a "Final OTP" if it does not align with the intention
of the previous TOF votes on the OTP, even if they personally agree with the
proposed "Final" wording.

An OTP is complete when 48 hours have elapsed and no TOF member has expressed
disagreement with the "Final OTP" wording having met the intentions of the TOF,
at which time it is merged into the repository.

---

[1]: https://github.com/openbmc/docs/blob/master/tof/contract.md
[2]: https://github.com/openbmc/technical-oversight-forum/issues/4
[3]: https://github.com/openbmc/technical-oversight-forum/issues
[4]: https://lists.ozlabs.org/listinfo/openbmc
[5]: https://lore.kernel.org/openbmc/

-- 
Patrick Williams

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: OTP-5: "OpenBMC TOF Proposal" Process
  2021-10-21  4:33 OTP-5: "OpenBMC TOF Proposal" Process Patrick Williams
@ 2021-10-21  4:47 ` Patrick Williams
  2021-10-29 16:29 ` Brad Bishop
  2021-10-29 16:37 ` Brad Bishop
  2 siblings, 0 replies; 7+ messages in thread
From: Patrick Williams @ 2021-10-21  4:47 UTC (permalink / raw)
  To: OpenBMC List

[-- Attachment #1: Type: text/plain, Size: 613 bytes --]

On Wed, Oct 20, 2021 at 11:33:51PM -0500, Patrick Williams wrote:
> 2. Use the OTP template for the proposal type to write a draft proposal and send
>    a copy to the [OpenBMC mailing list][4] with the title "OTP-N: Title" and the
>    contents being the filled-in OTP template.

I am fully aware we do not have OTP templates yet.  Much like how PEP-1[1]
defines the PEP process and PEP-12[2] gives the templates themselves, we will
have the templates come about through a future OTP.

1. https://www.python.org/dev/peps/pep-0001/
2. https://www.python.org/dev/peps/pep-0012/

-- 
Patrick Williams

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: OTP-5: "OpenBMC TOF Proposal" Process
  2021-10-21  4:33 OTP-5: "OpenBMC TOF Proposal" Process Patrick Williams
  2021-10-21  4:47 ` Patrick Williams
@ 2021-10-29 16:29 ` Brad Bishop
  2021-10-29 18:40   ` Patrick Williams
  2021-10-29 16:37 ` Brad Bishop
  2 siblings, 1 reply; 7+ messages in thread
From: Brad Bishop @ 2021-10-29 16:29 UTC (permalink / raw)
  To: Patrick Williams; +Cc: OpenBMC List

On Wed, Oct 20, 2021 at 11:33:51PM -0500, Patrick Williams wrote:
>As I mentioned in https://lore.kernel.org/openbmc/YXDrQAf73igsbu7+@heinlein/,
>the TOF needs a process for making proposals.  We have a bit of a cycle though
>in that we need a proposal for the process but we don't have a process for
>proposals.  So, this email is a proposal for the process for making proposals
>with which I am attempting to follow the proposed proposal process.
>
>Before I get into the proposal itself, the proposal proposes how the community
>should interact with proposals.  I propose that we all follow said
>proposal(s):

Thank you for this ^ 🤣

>Any member of the OpenBMC community may give feedback by:
>
>1. Expressing a vote to the top post of the Github issue.
>2. Providing grammatical suggestions to the Gerrit commit.
>3. Responding on the mailing list with opinions on non-grammatical OTP content.

I think I would just like to see the entire conversation happen on the 
list.  What would be the difficult parts with that?

>4. (Least desirable) Providing off-line feedback to a TOF member(s).

If it is undesirable why do we have it?  Maybe we could list that 
rationale to make sure this option is only used for those special cases?

>Community members should refrain from:
>
>1. Voting on any comment in the Github issues beyond the top post.
>2. Cluttering the mailing list discussion with grammatical suggestions.

I would agree this would be a minor annoyance but is it worth splitting 
the review process across both Gerrit and the list?  My opinion?  no.

-brad

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: OTP-5: "OpenBMC TOF Proposal" Process
  2021-10-21  4:33 OTP-5: "OpenBMC TOF Proposal" Process Patrick Williams
  2021-10-21  4:47 ` Patrick Williams
  2021-10-29 16:29 ` Brad Bishop
@ 2021-10-29 16:37 ` Brad Bishop
  2021-10-29 19:07   ` Patrick Williams
  2 siblings, 1 reply; 7+ messages in thread
From: Brad Bishop @ 2021-10-29 16:37 UTC (permalink / raw)
  To: Patrick Williams; +Cc: OpenBMC List

On Wed, Oct 20, 2021 at 11:33:51PM -0500, Patrick Williams wrote:

>## Definitions
>
>* OTP: An "OpenBMC TOF Proposal".  Any request to the TOF should be framed as
>  an OTP as documented by this process.
>
>* Author: The individual(s) who write the initial draft of the OTP.
>
>* Champion: A member of the TOF, confirmed by the current TOF chair, who will

What does confirmed mean here?  The chair will document the champion 
somewhere?  Also what if nobody on the TOF wants to volunteer to 
champion the proposal?  One will be appointed and try their hardest to 
represent the interests of the person making the proposal?

>  work with the Author while this process is being followed to ensure that
>  appropriate updates to the OTP are being made.  If the Author is a member of
>  the TOF it is expected that they will also act as Champion to their own OTP.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: OTP-5: "OpenBMC TOF Proposal" Process
  2021-10-29 16:29 ` Brad Bishop
@ 2021-10-29 18:40   ` Patrick Williams
  2021-10-29 18:49     ` Brad Bishop
  0 siblings, 1 reply; 7+ messages in thread
From: Patrick Williams @ 2021-10-29 18:40 UTC (permalink / raw)
  To: Brad Bishop; +Cc: OpenBMC List

[-- Attachment #1: Type: text/plain, Size: 2609 bytes --]

On Fri, Oct 29, 2021 at 12:29:54PM -0400, Brad Bishop wrote:
> On Wed, Oct 20, 2021 at 11:33:51PM -0500, Patrick Williams wrote:
> >Any member of the OpenBMC community may give feedback by:
> >
> >1. Expressing a vote to the top post of the Github issue.
> >2. Providing grammatical suggestions to the Gerrit commit.
> >3. Responding on the mailing list with opinions on non-grammatical OTP content.
> 
> I think I would just like to see the entire conversation happen on the 
> list.  What would be the difficult parts with that?

I listed voting in Github to avoid emails like "+1", but to allow the TOF to get
a general sentiment.

I put "grammatical suggestions" elsewhere because:
    1. Again, reducing clutter.
    2. The post here is mostly a 'draft' anyhow, which needs a follow-up in
       Gerrit later on for documentation purposes.
    3. I've previously heard sentiment along the lines that "Gerrit is good for
       code review but not for discussions".  Grammar is 'code review'.

The purpose of having proposals on the mailing list, I think, was to give
broader awareness and because it is easier to follow discussions in email.
Having minor comments on the mailing list means others have to sift through
those uninteresting emails which may reduce the visibility into the primary
discussion(s).

If we want to combine 2+3 together to have all community comments on the mailing
list, I don't think it drastically changes the proposal and seems just as fine
an approach.

> 
> >4. (Least desirable) Providing off-line feedback to a TOF member(s).
> 
> If it is undesirable why do we have it?  Maybe we could list that 
> rationale to make sure this option is only used for those special cases?

Even if we don't spell it out it is still going to happen.  You can't stop two
people from talking to each other.  Some people are not going to be comfortable
expressing their opinion in public but they might have an individual on the TOF
they are comfortable confiding in.  The "least desirable" is to spell out that
the preference is for opinions to be expressed in public.

I can certainly drop this or reword it if the consensus is as such.

> 
> >Community members should refrain from:
> >
> >1. Voting on any comment in the Github issues beyond the top post.
> >2. Cluttering the mailing list discussion with grammatical suggestions.
> 
> I would agree this would be a minor annoyance but is it worth splitting 
> the review process across both Gerrit and the list?  My opinion?  no.

I understand.  See above.

-- 
Patrick Williams

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: OTP-5: "OpenBMC TOF Proposal" Process
  2021-10-29 18:40   ` Patrick Williams
@ 2021-10-29 18:49     ` Brad Bishop
  0 siblings, 0 replies; 7+ messages in thread
From: Brad Bishop @ 2021-10-29 18:49 UTC (permalink / raw)
  To: Patrick Williams; +Cc: OpenBMC List

On Fri, Oct 29, 2021 at 01:40:09PM -0500, Patrick Williams wrote:
>On Fri, Oct 29, 2021 at 12:29:54PM -0400, Brad Bishop wrote:
>> On Wed, Oct 20, 2021 at 11:33:51PM -0500, Patrick Williams wrote:
>> >Any member of the OpenBMC community may give feedback by:
>> >
>> >1. Expressing a vote to the top post of the Github issue.
>> >2. Providing grammatical suggestions to the Gerrit commit.
>> >3. Responding on the mailing list with opinions on non-grammatical OTP content.
>>
>> I think I would just like to see the entire conversation happen on the
>> list.  What would be the difficult parts with that?
>
>I listed voting in Github to avoid emails like "+1", but to allow the TOF to get
>a general sentiment.

Agreed, I like this.  I was/am sort of thinking of the list/gerrit split.

>I put "grammatical suggestions" elsewhere because:
>    1. Again, reducing clutter.
>    2. The post here is mostly a 'draft' anyhow, which needs a follow-up in
>       Gerrit later on for documentation purposes.
>    3. I've previously heard sentiment along the lines that "Gerrit is good for
>       code review but not for discussions".  Grammar is 'code review'.
>
>The purpose of having proposals on the mailing list, I think, was to give
>broader awareness and because it is easier to follow discussions in email.
>Having minor comments on the mailing list means others have to sift through
>those uninteresting emails which may reduce the visibility into the primary
>discussion(s).
>
>If we want to combine 2+3 together to have all community comments on the mailing
>list, I don't think it drastically changes the proposal and seems just as fine
>an approach.

Ok.  Let's let others weigh in.

>> >4. (Least desirable) Providing off-line feedback to a TOF member(s).
>>
>> If it is undesirable why do we have it?  Maybe we could list that
>> rationale to make sure this option is only used for those special cases?
>
>Even if we don't spell it out it is still going to happen.  You can't stop two
>people from talking to each other.  Some people are not going to be comfortable
>expressing their opinion in public but they might have an individual on the TOF
>they are comfortable confiding in.  The "least desirable" is to spell out that
>the preference is for opinions to be expressed in public.
>
>I can certainly drop this or reword it if the consensus is as such.

Sounds good - was mostly wondering if you had any specific situations in 
mind.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: OTP-5: "OpenBMC TOF Proposal" Process
  2021-10-29 16:37 ` Brad Bishop
@ 2021-10-29 19:07   ` Patrick Williams
  0 siblings, 0 replies; 7+ messages in thread
From: Patrick Williams @ 2021-10-29 19:07 UTC (permalink / raw)
  To: Brad Bishop; +Cc: OpenBMC List

[-- Attachment #1: Type: text/plain, Size: 1867 bytes --]

On Fri, Oct 29, 2021 at 12:37:20PM -0400, Brad Bishop wrote:
> On Wed, Oct 20, 2021 at 11:33:51PM -0500, Patrick Williams wrote:
> 
> >## Definitions
> >
> >* OTP: An "OpenBMC TOF Proposal".  Any request to the TOF should be framed as
> >  an OTP as documented by this process.
> >
> >* Author: The individual(s) who write the initial draft of the OTP.
> >
> >* Champion: A member of the TOF, confirmed by the current TOF chair, who will
> 
> What does confirmed mean here?  The chair will document the champion 
> somewhere?  Also what if nobody on the TOF wants to volunteer to 
> champion the proposal?  One will be appointed and try their hardest to 
> represent the interests of the person making the proposal?

This might need to be worded differently.

I anticipated a few scenarios:

    1. Multiple individuals are all so excited about a proposal that they want
       to volunteer to be the champion.
    2. Only one individual is excited enough to volunteer to be a champion.
    3. No one is excited enough to volunteer.

In #2, the "confirmation" is easy.  In #1, the chair should pick one of them.
In #3, the chair should pick someone, yes, and as you said: try their hardest to
represent the interests of the person making the proposal.  I recollect we've 
discussed that others would be invited to the TOF discussions for their own
proposals, but I don't see where that is documented.  If that is so, acting as
champion shouldn't even require buy-in to the proposal itself and means more of
coordinating the after-effects of the decision(s).

> 
> >  work with the Author while this process is being followed to ensure that
> >  appropriate updates to the OTP are being made.  If the Author is a member of
> >  the TOF it is expected that they will also act as Champion to their own OTP.

-- 
Patrick Williams

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2021-10-29 19:08 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-10-21  4:33 OTP-5: "OpenBMC TOF Proposal" Process Patrick Williams
2021-10-21  4:47 ` Patrick Williams
2021-10-29 16:29 ` Brad Bishop
2021-10-29 18:40   ` Patrick Williams
2021-10-29 18:49     ` Brad Bishop
2021-10-29 16:37 ` Brad Bishop
2021-10-29 19:07   ` Patrick Williams

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).