fabric@lists.hyperledger.org | Maintainer nominations

Home Messages Hashtags Subgroups

Date Date 1 - 20 of 20

Maintainer nominations

David Enyeart

For those of you not attending the Fabric contributor meeting today where this topic was discussed...

- There was general agreement that documentation should not be split from Fabric repository unless there is a very compelling reason to do so.
- The expectation is that all the issues previously identified in this thread could be resolved without splitting out Fabric documentation.
- As a next step, the documentation team took an action to propose a workflow such that documentation content (including translated content) in the main Fabric repository could be delivered without the need for new documentation/translation specific project maintainers.

Dave Enyeart

"Christopher Ferris" ---11/26/2019 12:26:38 PM---I think that it is important not to conflate things. There's a request to add two maintainers who's

From: "Christopher Ferris" <chris.ferris@...>
To: Me <chris.ferris@...>
Cc: Pam Andrejko <pama@...>, fabric@...
Date: 11/26/2019 12:26 PM
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Sent by: fabric@...

I think that it is important not to conflate things. There's a request to add two maintainers who's role will be
to help manage the Fabric documentation. I think that should be handled independent of any discussion of repository disposition.
Let's please address the two PRs for Chris and Joe independent of this broader discussion.

The generated documentation *should be* generated from the source code, and should most certainly NOT be
segregated to another repository. The authored documentation, written by humans has for the most part been
developed by a mostly disjoint set of people than those who author the code. Now, it would certainly
be nice to ensure that the code and the documentation were kept in lock-step, and even managed such that the code and doc
(and tests) were all committed as a unit; but that has almost never been the case, and it is rare to see it in practice.

There's a different skill set in developing good documentation than there is in writing good code. Both types of skills are important
to a successful project, and especially to one as significant as Fabric. I don't see a problem in having the authored content
managed in a separate repository.

Another factor is that we wanted to integrate the i18n translations and associated workflow that us currently managed
as a Hyperledger Lab process to formally incorporate it into the same repository as we manage the english source
for the documentation. We had previously discussed reconsidering that when we had separated the docs from the
core Fabric repo, as Dave had suggested. I do think that we need to revisit all of that now that we are finally over on GH.

Chris

On Tue, Nov 26, 2019 at 9:45 AM Christopher Ferris via Lists.Hyperledger.Org <chris.ferris=gmail.com@...> wrote:

Show quoted text

On Mon, Nov 25, 2019 at 5:26 PM Pam Andrejko <pama@...> wrote:
All,

I would like to nominate two new Documentation maintainers for the Hyperledger Fabric project. They are Chris Gabriel (Hyperchain Labs) and Joe Alewine (IBM).

Chris has been an instrumental member of the Documentation community workgroup for several years now. In addition to being a regular content reviewer and contributor, he is a consumer of Fabric in his own Hyperchain Labs business that he founded. The insights, perspective, and content that he's provided based on his experience have been invaluable to the documentation work group and Fabric community as a whole.

Joe has been providing important Fabric documentation for over two and half years, is recognized as an expert on the ordering service, the Fabric upgrade process and channel capabilities, and was recently recognized as a Hyperledger significant contributor.

Adding two more Documentation Maintainers will greatly facilitate the addition and approval of Fabric documentation content going forward.

I have opened a separate PR for each nomination:

Chris Gabriel - https://github.com/hyperledger/fabric/pull/317
Joe Alewine - https://github.com/hyperledger/fabric/pull/316

I'm requesting that existing maintainers review the nominations and indicate whether they agree with a comment in the PR. Other’s are welcome to provide their input.

Warm regards,
Pam Andrejko

Zhenhua Zhao <zhao.zhenhua@...>

#7284

I’m glad to see doc is being a hot topic. Technical Working Group China(TWGC) has been working more than a year translating fabric doc into Chinese. There are more than 10 active volunteers who translate doc, we have tried different methods to collaborate with others, like using personal repo’s, hyperledger lab repo, or on personal local machine, and professional translating platform(I shared how to support multi-language docs on a fabric playback meeting).

I’d like share my options with you.

1. Documentation is quit different with code. Documentation has its owner format/structure, like .md, .rst, and a single topic may have .md files, .png files. The best way to write & review doc is with a WYSIWYG tool, like MS Word. Github is not a ideal tool for it.

2. With supporting i18n, a professional translating platform is required. Translating process is topic by topic, translating, reviewing then submit, it makes doc has different release rhythm, so using separated repos is better.

3. Writing/Reviewing documentation requires different skills with coding, especially for translating, doc maintainers are indeed needed.

Rich Zhao

Show quoted text

On Nov 27, 2019, at 1:08 AM, Yacov <yacovm@...> wrote:

I have no clue in AZP, perhaps Brett can shed some light here, but - can't you just put in our scripts something that does a git show --name-only and returns immediately in case there are only changes to markdown or RST files?

From: David Enyeart/Durham/IBM
To: "Gari Singh" <garis@...>
Cc: fabric@..., "Matthew Sykes" <matthew.sykes@...>, "Yacov Manevich" <YACOVM@...>
Date: 11/26/2019 06:02 PM
Subject: Re: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations

Ok, we're getting closer. CODEOWNERS does indeed buy us some options.

I think that would take us down to two remaining concerns with docs in Fabric repo. Anybody have ideas on solving these?

1) Doc translation - we could have a CODEOWNER per translation directory, but it still requires the translation CODEOWNER to be a Fabric maintainer, not something we'd want.

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

Dave Enyeart

From: "Gari Singh" <garis@...>
To: "Yacov Manevich" <YACOVM@...>
Cc: "Matthew Sykes" <matthew.sykes@...>, fabric@...
Date: 11/26/2019 09:52 AM
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Sent by: fabric@...

I too believe that the documentation belongs with the code. I also do not believe that every person who contributes should become a maintainer ... especially when they do not have a history of actually doing reviews. Likely some of the current maintainers should be retired as well given they do not do a lot of reviews. But I think people are actually missing the point that Matt is making. From the conversations I have seen, people believe that we do not merge changes to documentation fast enough. So the solution is to move them out to another repository and likely change the approval requirements to NACR (single approver). So we are making this change to avoid dealing with the fundamental issue: the heavyweight process we have for approving changes to the fabric repo. There are alternative solutions: Now let's say that we believe there are certain domains in the fabric codebase which we believe require review from a subset of "experts" on that code. This is easily handled by using CODEOWNERS and assigning a subset of maintainers to specific pieces of the code. We can NACR in general but will not be able to merge changes to certain parts of the code without a review from some on the CODEOWNERS list. ----------------------------------------- Gari Singh Distinguished Engineer, CTO - IBM Blockchain IBM Middleware 550 King St Littleton, MA 01460 Cell: 978-846-7499 garis@... ----------------------------------------- -----fabric@... wrote: ----- To: "Matthew Sykes" <matthew.sykes@...> From: "Yacov" Sent by: fabric@... Date: 11/26/2019 09:41AM Cc: fabric@... Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations 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 contributionsMaintainers 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@...

Christopher Ferris

#7283

I think that it is important not to conflate things. There's a request to add two maintainers who's role will be

to help manage the Fabric documentation. I think that should be handled independent of any discussion of repository disposition.

Let's please address the two PRs for Chris and Joe independent of this broader discussion.

The generated documentation *should be* generated from the source code, and should most certainly NOT be

segregated to another repository. The authored documentation, written by humans has for the most part been

developed by a mostly disjoint set of people than those who author the code. Now, it would certainly

be nice to ensure that the code and the documentation were kept in lock-step, and even managed such that the code and doc

(and tests) were all committed as a unit; but that has almost never been the case, and it is rare to see it in practice.

There's a different skill set in developing good documentation than there is in writing good code. Both types of skills are important

to a successful project, and especially to one as significant as Fabric. I don't see a problem in having the authored content

managed in a separate repository.

Another factor is that we wanted to integrate the i18n translations and associated workflow that us currently managed

as a Hyperledger Lab process to formally incorporate it into the same repository as we manage the english source

for the documentation. We had previously discussed reconsidering that when we had separated the docs from the

core Fabric repo, as Dave had suggested. I do think that we need to revisit all of that now that we are finally over on GH.

Chris

On Tue, Nov 26, 2019 at 9:45 AM Christopher Ferris via Lists.Hyperledger.Org <chris.ferris=gmail.com@...> wrote:

Show quoted text

I agree that these would be two good additions to the docs maintainership. I approve.

Chris

On Mon, Nov 25, 2019 at 5:26 PM Pam Andrejko <pama@...> wrote:
All,

I would like to nominate two new Documentation maintainers for the Hyperledger Fabric project. They are Chris Gabriel (Hyperchain Labs) and Joe Alewine (IBM).

Chris has been an instrumental member of the Documentation community workgroup for several years now. In addition to being a regular content reviewer and contributor, he is a consumer of Fabric in his own Hyperchain Labs business that he founded. The insights, perspective, and content that he's provided based on his experience have been invaluable to the documentation work group and Fabric community as a whole.

Joe has been providing important Fabric documentation for over two and half years, is recognized as an expert on the ordering service, the Fabric upgrade process and channel capabilities, and was recently recognized as a Hyperledger significant contributor.

Adding two more Documentation Maintainers will greatly facilitate the addition and approval of Fabric documentation content going forward.

I have opened a separate PR for each nomination:

Chris Gabriel - https://github.com/hyperledger/fabric/pull/317
Joe Alewine - https://github.com/hyperledger/fabric/pull/316

I'm requesting that existing maintainers review the nominations and indicate whether they agree with a comment in the PR. Other’s are welcome to provide their input.

Warm regards,
Pam Andrejko

Brett T Logan <brett.t.logan@...>

#7282

We could gate the DocBuild, UT and IT behind the success of VerifyBuild like we do today, and can set variables (BuildDoc and RunTests) as true or false and make them the conditions on which the DocBuild and UT and IT run, i.e. https://docs.microsoft.com/en-us/azure/devops/pipelines/process/expressions?view=azure-devops#dependencies (This is in .NET for Windows syntax, it wouldn't look exactly like this, but you get the idea)

Brett Logan

Software Engineer, IBM Blockchain

Phone: 1-984-242-6890

E-mail: brett.t.logan@...

Show quoted text

----- Original message -----
From: "Yacov" <yacovm@...>
Sent by: fabric@...
To: "David Enyeart" <enyeart@...>
Cc: "Gari Singh" <garis@...>, fabric@..., "Matthew Sykes" <matthew.sykes@...>, "Brett T Logan" <Brett.T.Logan@...>
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Date: Tue, Nov 26, 2019 12:08 PM

I have no clue in AZP, perhaps Brett can shed some light here, but - can't you just put in our scripts something that does a git show --name-only and returns immediately in case there are only changes to markdown or RST files?

From: David Enyeart/Durham/IBM
To: "Gari Singh" <garis@...>
Cc: fabric@..., "Matthew Sykes" <matthew.sykes@...>, "Yacov Manevich" <YACOVM@...>
Date: 11/26/2019 06:02 PM
Subject: Re: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations

Ok, we're getting closer. CODEOWNERS does indeed buy us some options.

I think that would take us down to two remaining concerns with docs in Fabric repo. Anybody have ideas on solving these?

1) Doc translation - we could have a CODEOWNER per translation directory, but it still requires the translation CODEOWNER to be a Fabric maintainer, not something we'd want.

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

Dave Enyeart

From: "Gari Singh" <garis@...>
To: "Yacov Manevich" <YACOVM@...>
Cc: "Matthew Sykes" <matthew.sykes@...>, fabric@...
Date: 11/26/2019 09:52 AM
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Sent by: fabric@...

I too believe that the documentation belongs with the code. I also do not believe that every person who contributes should become a maintainer ... especially when they do not have a history of actually doing reviews. Likely some of the current maintainers should be retired as well given they do not do a lot of reviews. But I think people are actually missing the point that Matt is making. From the conversations I have seen, people believe that we do not merge changes to documentation fast enough. So the solution is to move them out to another repository and likely change the approval requirements to NACR (single approver). So we are making this change to avoid dealing with the fundamental issue: the heavyweight process we have for approving changes to the fabric repo. There are alternative solutions: Now let's say that we believe there are certain domains in the fabric codebase which we believe require review from a subset of "experts" on that code. This is easily handled by using CODEOWNERS and assigning a subset of maintainers to specific pieces of the code. We can NACR in general but will not be able to merge changes to certain parts of the code without a review from some on the CODEOWNERS list. ----------------------------------------- Gari Singh Distinguished Engineer, CTO - IBM Blockchain IBM Middleware 550 King St Littleton, MA 01460 Cell: 978-846-7499 garis@... ----------------------------------------- -----fabric@... wrote: ----- To: "Matthew Sykes" <matthew.sykes@...> From: "Yacov" Sent by: fabric@... Date: 11/26/2019 09:41AM Cc: fabric@... Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations 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 contributionsMaintainers 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@...

Yacov

#7281

I have no clue in AZP, perhaps Brett can shed some light here, but - can't you just put in our scripts something that does a git show --name-only and returns immediately in case there are only changes to markdown or RST files?

From: David Enyeart/Durham/IBM
To: "Gari Singh" <garis@...>
Cc: fabric@..., "Matthew Sykes" <matthew.sykes@...>, "Yacov Manevich" <YACOVM@...>
Date: 11/26/2019 06:02 PM
Subject: Re: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations

Ok, we're getting closer. CODEOWNERS does indeed buy us some options.

I think that would take us down to two remaining concerns with docs in Fabric repo. Anybody have ideas on solving these?

1) Doc translation - we could have a CODEOWNER per translation directory, but it still requires the translation CODEOWNER to be a Fabric maintainer, not something we'd want.

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

Dave Enyeart

From: "Gari Singh" <garis@...>
To: "Yacov Manevich" <YACOVM@...>
Cc: "Matthew Sykes" <matthew.sykes@...>, fabric@...
Date: 11/26/2019 09:52 AM
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Sent by: fabric@...

I too believe that the documentation belongs with the code. I also do not believe that every person who contributes should become a maintainer ... especially when they do not have a history of actually doing reviews. Likely some of the current maintainers should be retired as well given they do not do a lot of reviews. But I think people are actually missing the point that Matt is making. From the conversations I have seen, people believe that we do not merge changes to documentation fast enough. So the solution is to move them out to another repository and likely change the approval requirements to NACR (single approver). So we are making this change to avoid dealing with the fundamental issue: the heavyweight process we have for approving changes to the fabric repo. There are alternative solutions: Now let's say that we believe there are certain domains in the fabric codebase which we believe require review from a subset of "experts" on that code. This is easily handled by using CODEOWNERS and assigning a subset of maintainers to specific pieces of the code. We can NACR in general but will not be able to merge changes to certain parts of the code without a review from some on the CODEOWNERS list. ----------------------------------------- Gari Singh Distinguished Engineer, CTO - IBM Blockchain IBM Middleware 550 King St Littleton, MA 01460 Cell: 978-846-7499 garis@... ----------------------------------------- -----fabric@... wrote: ----- To: "Matthew Sykes" <matthew.sykes@...> From: "Yacov" Sent by: fabric@... Date: 11/26/2019 09:41AM Cc: fabric@... Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations 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.

Show quoted text

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 contributionsMaintainers 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@...

David Enyeart

#7280

Ok, we're getting closer. CODEOWNERS does indeed buy us some options.

I think that would take us down to two remaining concerns with docs in Fabric repo. Anybody have ideas on solving these?

1) Doc translation - we could have a CODEOWNER per translation directory, but it still requires the translation CODEOWNER to be a Fabric maintainer, not something we'd want.

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

Dave Enyeart

"Gari Singh" ---11/26/2019 09:52:57 AM---I too believe that the documentation belongs with the code. I also do not believe that every person

From: "Gari Singh" <garis@...>
To: "Yacov Manevich" <YACOVM@...>
Cc: "Matthew Sykes" <matthew.sykes@...>, fabric@...
Date: 11/26/2019 09:52 AM
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations
Sent by: fabric@...

Show quoted text

Gari Singh <garis@...>

#7279

I too believe that the documentation belongs with the code.
I also do not believe that every person who contributes should become a maintainer ... especially when they do not have a history of actually doing reviews.
Likely some of the current maintainers should be retired as well given they do not do a lot of reviews.

But I think people are actually missing the point that Matt is making.  From the conversations I have seen, people believe that we do not merge changes to documentation fast enough.  So the solution is to move them out to another repository and likely change the approval requirements to NACR (single approver).  So we are making this change to avoid dealing with the fundamental issue:  the heavyweight process we have for approving changes to the fabric repo.

There are alternative solutions:

Now let's say that we believe there are certain domains in the fabric codebase which we believe require review from a subset of "experts" on that code.  This is easily handled by using CODEOWNERS and assigning a subset of maintainers to specific pieces of the code.  We can NACR in general but will not be able to merge changes to certain parts of the code without a review from some on the CODEOWNERS list.




-----------------------------------------
Gari Singh
Distinguished Engineer, CTO - IBM Blockchain
IBM Middleware
550 King St
Littleton, MA 01460
Cell: 978-846-7499
garis@...
-----------------------------------------

-----fabric@... wrote: -----
To: "Matthew Sykes" <matthew.sykes@...>
From: "Yacov" 
Sent by: fabric@...
Date: 11/26/2019 09:41AM
Cc: fabric@...
Subject: [EXTERNAL] Re: [Hyperledger Fabric] Maintainer nominations

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 poolsIn 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 contributionsMaintainers 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@...

David Enyeart

#7278

I also feel that the 'default' position should be that docs reside with the code repo, and there would need to be a compelling reason to split them out. In my opinion given the recent changes, there are now compelling enough reasons to split the Fabric docs out as mentioned below, but not yet compelling enough reasons to split out the other repo's docs (we haven't seen the problems I mentioned in those repos). If you don't want to split Fabric docs, what is your alternate suggestion for handling doc translation and additional doc maintainers?

Concerning the requirement for 'majority' to approve fabric-rfcs, the fabric-rfcs proposal was out for review for several weeks. What is your alternate proposal?

Concerning the requirement for 'two mandatory reviews', the last time I informally polled the maintainers there was not support. But given the fact that you cannot self +2 in GitHub, I suspect views may be changing there as well.

In all three cases, I'd urge you to propose specific changes/solutions, and let's see if we can find some consensus on each.

Dave Enyeart

"Matthew Sykes" ---11/26/2019 09:29:15 AM---For the record, I am not in favor of extracting the documentation. I strongly feel that the doc and

From: "Matthew Sykes" <matthew.sykes@...>
To: fabric@...
Date: 11/26/2019 09:29 AM
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:

"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:

yacovm@...

To:

bbehlendorf@...

Cc:

fabric@...

Date:

Subject:

Sent by:

fabric@...

All maintainers of code repositories should be able to merge documentation contributions
Maintainers of the documentation should not be able to merge code contributions.

From:

bbehlendorf@...

To:

fabric@...

Date:

Subject:

Sent by:

fabric@...

Show quoted text

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

Christopher Ferris

#7277

I agree that these would be two good additions to the docs maintainership. I approve.

Chris

Show quoted text

On Mon, Nov 25, 2019 at 5:26 PM Pam Andrejko <pama@...> wrote:

All,

I would like to nominate two new Documentation maintainers for the Hyperledger Fabric project. They are Chris Gabriel (Hyperchain Labs) and Joe Alewine (IBM).

Chris has been an instrumental member of the Documentation community workgroup for several years now. In addition to being a regular content reviewer and contributor, he is a consumer of Fabric in his own Hyperchain Labs business that he founded. The insights, perspective, and content that he's provided based on his experience have been invaluable to the documentation work group and Fabric community as a whole.

Joe has been providing important Fabric documentation for over two and half years, is recognized as an expert on the ordering service, the Fabric upgrade process and channel capabilities, and was recently recognized as a Hyperledger significant contributor.

Adding two more Documentation Maintainers will greatly facilitate the addition and approval of Fabric documentation content going forward.

I have opened a separate PR for each nomination:

Chris Gabriel - https://github.com/hyperledger/fabric/pull/317
Joe Alewine - https://github.com/hyperledger/fabric/pull/316

I'm requesting that existing maintainers review the nominations and indicate whether they agree with a comment in the PR. Other’s are welcome to provide their input.

Warm regards,
Pam Andrejko

Yacov

#7276

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

Show quoted text

"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@...

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

Up to you all,

Brian

-- Brian Behlendorf Executive Director, Hyperledger
bbehlendorf@...Twitter: @brianbehlendorf

--
Matthew Sykes
matthew.sykes@...

Matthew Sykes

#7275

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.

Show quoted text

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 able to 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@...

Jay Guo

#7273

Just in case i wasn't stating my opinion clearly, i'd suggest to separate docs from code, and have multiple languages dirs within it, e.g.

content

|- en

|- zh

|- de

- J

Show quoted text

On Tue, Nov 26, 2019 at 9:25 PM Jay Guo via Lists.Hyperledger.Org <guojiannan1101=gmail.com@...> wrote:

from translation point of view, i've seen some popular projects like k8s and tensorflow that separate docs from code, where i18n is first class citizen within the dir structure, for example [1] and [2].

we, technical working group china, has been translating docs to Chinese via [3] and serve it from our own readthedocs domain. This has been giving us problems in marketing the material, leveraging community tools, and incentivizing translators.

With CODEOWNERS, i think we will be able to have fine-grained maintainership across different languages

[1] https://github.com/kubernetes/website/tree/master/content
[2] https://github.com/tensorflow/docs/tree/master/site
[3] https://github.com/hyperledger-labs/fabric-docs-cn

On Tue, Nov 26, 2019 at 8:11 PM 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 able to 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

Jay Guo

#7272

from translation point of view, i've seen some popular projects like k8s and tensorflow that separate docs from code, where i18n is first class citizen within the dir structure, for example [1] and [2].

we, technical working group china, has been translating docs to Chinese via [3] and serve it from our own readthedocs domain. This has been giving us problems in marketing the material, leveraging community tools, and incentivizing translators.

With CODEOWNERS, i think we will be able to have fine-grained maintainership across different languages

[1] https://github.com/kubernetes/website/tree/master/content

[2] https://github.com/tensorflow/docs/tree/master/site

[3] https://github.com/hyperledger-labs/fabric-docs-cn

Show quoted text

On Tue, Nov 26, 2019 at 8:11 PM 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 able to 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

David Enyeart

#7271

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 able to 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@...

Show quoted text

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

Up to you all,

Brian

-- Brian Behlendorf Executive Director, Hyperledger
bbehlendorf@...Twitter: @brianbehlendorf

Yacov

#7267

I think the best solution for these 2 seemingly conflicting ideas is:

All maintainers of code repositories should be able to 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@...

Show quoted text

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

Up to you all,

Brian

-- Brian Behlendorf Executive Director, Hyperledgerbbehlendorf@...Twitter: @brianbehlendorf

Anthony O'Dowd <a_o-dowd@...>

#7266

Thank you Pam.

I'm very much in favour of these two nominations, and personally, I'd like to see more maintainers and contributors to Hyperledger Fabric in general, and documentation in particular.

On a related note, an additional request would be to support the work that Rich Zhao started on Chinese language docs. With our move to GitHub, and the soon creation of a separate docs repo, two of the items that Rich requires to make progress are overcome. A final requirement would be a Chinese language docs maintainer. I'd be happy to discuss this topic and the introduction of other languages on the next Documentation workgroup calls -- it's probably most relevant on the Eastern hemi call. I'll add an item to both agendas.

Thanks, Anthony.

Brian Behlendorf <bbehlendorf@...>

#7264

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?

Up to you all,

Brian

-- 
Brian Behlendorf
Executive Director, Hyperledger
bbehlendorf@...
Twitter: @brianbehlendorf

David Enyeart

#7263

Our intent has been to split Fabric docs into its own repository after the transition to GitHub and Azure Pipelines. We only have one more repository to switch over (fabric-test), then will proceed with the documentation split. If anybody would like to drive the documentation split in parallel, that would certainly expedite things.

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.

Dave Enyeart

"Pam Andrejko" ---11/25/2019 05:26:48 PM---All, I would like to nominate two new Documentation maintainers for the Hyperledger Fabric project.

From: "Pam Andrejko" <pama@...>
To: fabric@...
Date: 11/25/2019 05:26 PM
Subject: [EXTERNAL] [Hyperledger Fabric] Maintainer nominations
Sent by: fabric@...

All,

I would like to nominate two new Documentation maintainers for the Hyperledger Fabric project. They are Chris Gabriel (Hyperchain Labs) and Joe Alewine (IBM).

Chris has been an instrumental member of the Documentation community workgroup for several years now. In addition to being a regular content reviewer and contributor, he is a consumer of Fabric in his own Hyperchain Labs business that he founded. The insights, perspective, and content that he's provided based on his experience have been invaluable to the documentation work group and Fabric community as a whole.

Joe has been providing important Fabric documentation for over two and half years, is recognized as an expert on the ordering service, the Fabric upgrade process and channel capabilities, and was recently recognized as a Hyperledger significant contributor.

Adding two more Documentation Maintainers will greatly facilitate the addition and approval of Fabric documentation content going forward.

I have opened a separate PR for each nomination:

Chris Gabriel - https://github.com/hyperledger/fabric/pull/317
Joe Alewine - https://github.com/hyperledger/fabric/pull/316

I'm requesting that existing maintainers review the nominations and indicate whether they agree with a comment in the PR. Other’s are welcome to provide their input.

Warm regards,
Pam Andrejko

Yacov

#7261

> and was recently recognized as a Hyperledger significant contributor.

Just for the record.... only IBMers can access this link....

From: "Pam Andrejko" <pama@...>
To: fabric@...
Date: 11/26/2019 12:26 AM
Subject: [EXTERNAL] [Hyperledger Fabric] Maintainer nominations
Sent by: fabric@...

Chris Gabriel - https://github.com/hyperledger/fabric/pull/317
Joe Alewine - https://github.com/hyperledger/fabric/pull/316

I'm requesting that existing maintainers review the nominations and indicate whether they agree with a comment in the PR. Other’s are welcome to provide their input.

Warm regards,
Pam Andrejko

Pam Andrejko

#7260

Chris Gabriel - https://github.com/hyperledger/fabric/pull/317
Joe Alewine - https://github.com/hyperledger/fabric/pull/316

I'm requesting that existing maintainers review the nominations and indicate whether they agree with a comment in the PR. Other’s are welcome to provide their input.

Warm regards,
Pam Andrejko

1 - 20 of 20

Previous Topic Next Topic

Home Hashtags Subgroups Terms