Re: Maintainer nominations


Yacov
 

The SDK documentation and CA is only documentation about APIs, it's not documentation about concepts, ideas, and tutorials.

I don't think that extracting the fabric documentation files out of the fabric repository would harm contribution - why would it ?

You can just link to the document repository from the readme.md of the Fabric repository and everyone would find it just as they find the files inside the docs repository.

> The repositories were not separated because they had different maintainer pools
In the past, the fabric-CA and fabric-node-SDK repositories inherited the maintainers of the fabric core, and that was a bad thing, because the only people that could merge code were those in the intersection of understanding the code in the corresponding repositories, and that were also fabric core maintainers.
As time went by, they were given their own maintainers and then progress was quicker.




From:        "Matthew Sykes" <matthew.sykes@...>
To:        fabric@...
Date:        11/26/2019 04:29 PM
Subject:        [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Sent by:        fabric@...




For the record, I am not in favor of extracting the documentation. I strongly feel that the doc and the code should live together where feasible. My perspective is that lowering the barriers to contribute is far better than segmenting the ecosystem into a number of fiefdoms.

If we want doc changes to only require a single doc review, we should state that's the desired process and put a technology plan in place to make that happen.

With that, a few comments to Dave's note:

> As Fabric has grown the sets of maintainers has naturally diverged across the fabric-* repos. The core Fabric maintainers are naturally different from the Fabric CA maintainers, the Java SDK maintainers, the Node.js SDK maintainers, etc. 

The repositories were not separated because they had different maintainer pools; they were separated because, in most cases, they use fundamentally different implementation and CI processes. I'll also note that each of these contain their own documentation tree. (There's a docs folder in CA and API documentation is part of the code in node and Java.) Are you proposing we split all of these out as well?

> It has been challenging to get a majority of core Fabric maintainers to weigh in on decisions, since only about half of the maintainers are active day-to-day. This becomes more of an issue with the recent introduction of the fabric-rfcs process, which requires a majority of Fabric maintainers to agree before taking on new enhancements.

This is a problem of our own making. We have far too much process in place to make rapid forward movement. It's our choice to require a "majority" of maintainers and "2 mandatory reviews" to integrate things.


On Tue, Nov 26, 2019 at 7:11 AM David Enyeart <enyeart@...> wrote:
The intent of my proposal was exactly as Yacov says - doc maintainers would be comprised of the core Fabric maintainers in addition to heavy doc contributors/reviewers.

I do understand Brian's point, and we have been hesitant to split fabric code and fabric docs repos/maintainers up until now for the reasons Brian mentions. However in my opinion the time has come to split them for the following reasons:

As Fabric has grown the sets of maintainers has naturally diverged across the fabric-* repos. The core Fabric maintainers are naturally different from the Fabric CA maintainers, the Java SDK maintainers, the Node.js SDK maintainers, etc. We've had good results with different maintainers for each of these repos.

It has been challenging to get a majority of core Fabric maintainers to weigh in on decisions, since only about half of the maintainers are active day-to-day. This becomes more of an issue with the recent introduction of the fabric-rfcs process, which requires a majority of Fabric maintainers to agree before taking on new enhancements.

With the transition to Azure Pipelines, there is not (yet) an easy way to suppress CI for doc-only PRs.

With the transition to GitHub, we would like different branch protection rules for Fabric code and Fabric docs.


Dave Enyeart

"Yacov" ---11/26/2019 01:49:37 AM---I think the best solution for these 2 seemingly conflicting ideas is: All maintainers of code reposi

From:
"Yacov" <yacovm@...>
To:
"Brian Behlendorf" <bbehlendorf@...>
Cc:
fabric@...
Date:
11/26/2019 01:49 AM
Subject:
[EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Sent by:
fabric@...




I think the best solution for these 2 seemingly conflicting ideas is:
  • All maintainers of code repositories should be ableto merge documentation contributions
  • Maintainers of the documentation should not be able to merge code contributions.



From:
"Brian Behlendorf" <bbehlendorf@...>
To:
fabric@...
Date:
11/26/2019 07:36 AM
Subject:
[EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Sent by:
fabric@...




On 11/25/19 6:09 PM, David Enyeart wrote:
I'd suggest that we identify the top documentation contributors and reviewers to seed the fabric docs repository maintainer list in the coming weeks (including Chris and Joe), rather than pulling the trigger in the Fabric repository this week.

Are there separate maintainer pools for different fabric-* repos?

If so, I can understand the argument, coming from a world where the precautionary principle would apply, and where prior version control systems (and even earlier versions of git) allowed for a dangerous degree of repository damage if someone made the wrong set of changes. I also of course get the point for different maintainers for different Hyperledger projects, e.g. Fabric vs Sawtooth.

But for the same project, which is arguably the same "community" of contributors and representatives of end-users, you may want to consider a single pool of maintainers across all fabric-* repos. The easy case is to argue for the ability for anyone who's a maintainer on the main code repos to also be able to merge in changes into docs-related repos. The harder case is for people who come in as solid contributors to docs, but aren't (yet!) code contributors. There, I'd still argue for it - the boundary between docs and code is rarely so hard, as changes to error messages/logging or admin/user interfaces often are driven by a docs-level view of what would be easier to explain. And, I've seen great core developers on projects come in first through a docs-related role. Also, just for simplicity: I'll counter your precautionary principle with an Occam's Razor, which makes understanding the project easier for newcomers. I bet reversing any mistaken merges is a lower cost than the value of contributions you might not otherwise see.

Up to you all,

Brian

--
Brian Behlendorf
Executive Director, Hyperledger

bbehlendorf@...
Twitter: @brianbehlendorf








--
Matthew Sykes
matthew.sykes@...



Join fabric@lists.hyperledger.org to automatically receive all group messages.