Page MenuHomeFreeBSD

Multiple updates for the committer guide
AbandonedPublic

Authored by eadler on Jul 1 2018, 12:04 AM.

Details

Reviewers
imp
seanc
Group Reviewers
Core Team
Summary

committer guide: update rules for contrib software.

  • Most notably don't require talking to core@ to take on maintainership.
  • Merge an FAQ into the main body of the text
  • Wordsmith

Committer guide: avoid confusing maintainers with hats

The content at administration.html discussed hats, not maintainers.
While certain people do tend to own various areas, this is covered by
MAINTAINERS, Herald, etc. Just remove the reference to administration
since its off-topic in this context.

Committer guide: add note about private discussions

While I could have written this section on my own, the book Producing
OSS describes the issues better than I can. Incorporate by reference.

Comitter guide: rewrite the section on testing.

  • The previous version felt a little condescending or blame-y. Rewrite

to reduce the blame on the individual but still make strong statements
about needing to test

(ignore this part; its pending review from ports-secteam; but it was
hard to separate out in this one mega-review)
Committer guide: expand ports-secteam blanket

This approves two additional blankets:

  • security issues version bumps
  • crash version bumps

Diff Detail

Lint
No Linters Available
Unit
No Unit Test Coverage
Build Status
Buildable 17758
Build 17547: arc lint + arc unit

Event Timeline

eadler created this revision.Jul 1 2018, 12:04 AM
eadler added inline comments.
en_US.ISO8859-1/articles/committers-guide/article.xml
4450

ignore this part. Its pending a separate review.

imp requested changes to this revision.Jul 1 2018, 1:52 AM
imp added a subscriber: imp.

a couple of preliminary comments, more later.

en_US.ISO8859-1/articles/committers-guide/article.xml
3476–3477

this duplicates the above.

3536

This needs a lot of work, it's kinda preachy now

This revision now requires changes to proceed.Jul 1 2018, 1:52 AM
eadler updated this revision to Diff 44704.EditedJul 1 2018, 3:11 AM

private technical conversations:

  • Reduce preachyness, and give more actionable advice.

contributed code:

  • reduce duplication
eadler added inline comments.Jul 1 2018, 3:13 AM
en_US.ISO8859-1/articles/committers-guide/article.xml
3476–3477

One's the title, the other is the details. I'll update to make this a bit clearer.

imp added inline comments.Jul 1 2018, 3:46 AM
en_US.ISO8859-1/articles/committers-guide/article.xml
3537

this is a giant it depends. There's often times that it's useful to poll others privately about a change you think might be contentious to build consensus or to learn of obvious pitfalls before proposing something in public. There's times when asking person X directly beats asking on the mailing list because X is the one who knows things the best, but rarely reads mailing lists. There are other times that public discussions are quite useful. I don't think we can have such a wide-reaching blanket statement, especially if people take a too-expansive view on this and use it as a stick to beat developers who, frankly, have done nothing wrong.

eadler added a comment.Jul 1 2018, 3:48 AM

(fwiw, If there only contentious part is the new words about private discussions, I'd like approval to commit the other parts first. This will make it easier to track and review)

bcr added a subscriber: bcr.Jul 1 2018, 10:09 AM

A few suggestions on fixes (a missing word, typo, and line breaks).

en_US.ISO8859-1/articles/committers-guide/article.xml
3514

s/convertion/conversation/

3521

there is an "are" missing here after "you"

3526

You can pull the "<link" part into the previous line, break it at "xlink" (indenting that one) and break the line after "Producing" again.

seanc added a subscriber: seanc.Jul 1 2018, 7:16 PM
seanc requested changes to this revision.Jul 1 2018, 9:20 PM
seanc added a subscriber: allanjude.

Provide some feedback and suggested some alternate wording.

en_US.ISO8859-1/articles/committers-guide/article.xml
3509

Err... wait. This is a value judgement that isn't necessarily true and that it's worth teasing out a bit of nuance.

Discussing technical topics in public casts a wide net and may attract a wide audience of participants. A wide net of participants cuts in two ways:

  • competent and sufficiently qualified people may participate (good)
  • unqualified opinions may also participate, and can negatively impact the signal to noise ratio (bad)

It is not uncommon for people to not realize the limitations in their understanding and to participate. One consequence of this phenomena is that qualified opinions will need to either wade through this discussion (which expends precious effort and executive capacity). It is also entirely too common for participation in a discussion to be misconstrued as authority or domain expertise.

I'm not suggesting it is unimportant to invest in teaching people and to grow the community, but it's also important to be mindful of the activation energy of getting someone qualified to participate in community discussions. The results of private discussions should always be made public for the benefit of the community. We have many examples of this where subject matter experts get together in small groups or offline to discuss many different technical details. This offline practice is generally perceived to be helpful and appreciated by participants.

The objection is the word "always." I agree with the rest of the paragraph in that FreeBSD is an open source operating system, however our goal is to ship the best open code available. Given that a number of us are commercially oriented in our thinking and motivations, this also means that we're on the clock with regards to our contributions and need to be efficient in our use of everyone's time. We put process guidelines in place to aid in good and healthy outcomes and to strike a balance between open and fully transparent, and productive and efficient.

Would it be possible to rephrase this in the positive instead? Something like:

<listeitem>
<para>Conduct discussions in public or report the results of discussions to public forums.</para>

<para>&os is a trusted Open Source project because of its emphasis on transparency and disclosure.  Where
reasonable, conducting discussions in public forums is encouraged (notably because there is no effort
required to summarize the outcome for the public).  Where this is not possible, due to subject mater
expertise or timeliness, the results of technical discussions and topics should be made public so the
project's working memory can be enriched through a shared understanding of the outcome from subject
matter experts.  The trade-off of productivity from focused conversations vs the cost of summarizing
the outcome of a discussion is left to the best judgement of the participants.</para>

<para>If you think something should be discussed in public, suggest to the other participants to have the
discussion in public, or to make the summary available of a discussion available so the community at large
may benefit from the rationale that lead up to a decision.  Reminder: it is not acceptable to unilaterally
make a discussion or summary available in a public forum without consent (e.g. &a.developers; or private
correspondence).  In the end, use good judgement to facilitate productive communication practices between
individuals and be mindful of our open source community writ-large (including but not limited to: commercial
users, appliance vendors, open source enthusiasts, students, and service providers).</para>
</listitem>

Does that work for you? If so, can you also chase that updated title elsewhere in this patch?

This revision now requires changes to proceed.Jul 1 2018, 9:20 PM
eadler abandoned this revision.Jul 2 2018, 1:56 AM

I am not dropping this discussion, just going to split this review up. Expect to see an updated review, with your comments addressed, in the next week or so

en_US.ISO8859-1/articles/committers-guide/article.xml
3509

(I have some more to say here, but it is getting late for me. I don't necessarily agree with the text as above). I will also split up this review into separate ones since I figured out an easier way to handle this on my side, and the different patches are not conflicting as I thought they might be.

imp added a comment.Jul 2 2018, 2:59 AM

I am not dropping this discussion, just going to split this review up. Expect to see an updated review, with your comments addressed, in the next week or so

It isn't about your views. It's about the project's views and core's notions of where to put and not put emphasis on in a guide to fellow committers.

eadler added a comment.Jul 2 2018, 3:07 AM
In D16080#341072, @imp wrote:

I am not dropping this discussion, just going to split this review up. Expect to see an updated review, with your comments addressed, in the next week or so

It isn't about your views. It's about the project's views and core's notions of where to put and not put emphasis on in a guide to fellow committers.

I get that. That changes nothing about the above response.