New Fabric Documentation merge process proposal


Pam Andrejko
 

 
On one of the recent contributors calls there was a discussion about a the process for merging Fabric documentation content. As a result of that discussion, we would like to propose a new process for getting documentation content merged.
 
Note that although there has been discussion about moving to a new Fabric repo, for now we’d like to leave the documentation in the existing Fabric repo in order to maintain developer contribution and engagement and in order to keep the docs in sync with the Fabric releases and code. Of course, this does not preclude us from moving it to its own repo in the future if we decide there are additional benefits to be gained.
 
Why do we want to modify the process?
- Encourage more community contribution by including more contributors in the process.
- Simplify the process to merge trivial changes to the documentation.
- Facilitate inclusion of translated content in ReadTheDocs.
 
Proposal:
1. If a PR contains both documentation and code updates, use the existing Fabric code review and approval process.
2. If a PR contains content only under the /docs folder - then a default set of documentation reviewers are automatically notified by GitHub. To start, we propose the reviewer list include: Anthony, Joe, Nik, Pam, Chris Gabriel, Jim Mason, Lesley-Ann Jordan. Note that Fabric Maintainers will also still be notified.
3. A Documentation PR can be merged by a non-author Documentation Maintainer - whose merge capability is restricted to the /docs folder. We propose this list include:   Anthony O'Dowd, Joe Alewine, Nik Gupta, Pam Andrejko, Chris Gabriel, FUTURE: Rich Zhao (for translated content, once we have the process sorted out). 
 
We have reviewed this process with Brett Logan and he has figured out an automated way for this to work (thank you Brett):
  • Add a new maintainers team to the Fabric repository - `Documentation Maintainers` where membership to this group is managed by the Linux Foundation.
  • Configure a mergify bot such that after:
    1. The documentation PR is approved by a Documentation Maintainer using the normal "Review changes" pane,  and 
    2. The Documentation Maintainer adds the label `doc-approve` to a documentation PR.
  •  Then, the mergify bot runs and the content is merged. 
  • Because the traditional "Merge" button will be disabled for Documentation Maintainers, they have to add the `doc-approve` label to trigger the bot merge. 
  • Non-documentation Maintainers can still continue to the use the merge button to merge documentation PRs as per usual.
  • The bot is configured such that Documentation Maintainers are restricted to merging PRs under the /docs folder.
  • For adding or removing documentation maintainers, we can add a 'Documentation Maintainers' table to MAINTAINERS.md
  • Then, submit a PR against that table, collect the votes, and merge.
  • Someone from the Linux Foundation updates the team definition per the table.
 
Documentation Maintainers are allowed to propose new Documentation reviewers and new Documentation Maintainers.
 
Criteria to become a Documentation Maintainer:
 
A track record of sustained documentation leadership  in the form of GitHub reviews or contributions, or consistent documentation workgroup contributions, or translation contribution.
 
We welcome your feedback and comments.

Pam Andrejko

 
 

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