Updating and Relocating Repository Structure and Maintainers Instructions

guidelines/MAINTAINERS-guidelines.md → governing-documents/MAINTAINERS-file.md

@@ -1,17 +1,19 @@
 ---
 layout: default
 title: MAINTAINERS Guidelines
-parent: Guidelines
+parent: Governing Documents
 grand_parent: LF Decentralized Trust TAC
 nav_order: 2
 ---
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 
 ## Introduction
 
-All Hyperledger repositories **MUST** have a `MAINTAINERS.md` file at the top-level directory of the source code. The [SAMPLE-MAINTAINERS.md](SAMPLE-MAINTAINERS.md) can be used as a template by projects creating a new repository.
+All Linux Foundation Decentralized Trust (LFDT) repositories **MUST** have a `MAINTAINERS.md` file at the top-level directory of the source code. The [SAMPLE-MAINTAINERS.md](SAMPLE-MAINTAINERS.md) can be used as a template by projects creating a new repository.
 
-The Hyperledger Foundation GitHub organization administrators **SHOULD** periodically send out notifications about missing `MAINTAINERS.md` files.
+The Technical Steering Committee (TSC) for the project to which a repository belongs **MUST** periodically send out notifications about missing `MAINTAINERS.md` files.
+
+The LFDT GitHub organization administrators (i.e., LFDT TAC) **SHOULD** periodically send out notifications about missing `MAINTAINERS.md` files.
 
 The following provides guidelines and suggested content to include in the `MAINTAINERS.md` file.
 
@@ -28,17 +30,17 @@ In most repositories, the "Maintainer" scope is given to all repository
 Maintainers. The "Maintainer" scope is defined as the "Maintain" GitHub role.
 This is usually sufficient to do all of the work required of a Maintainer. From
 time to time, Maintainers may have to request certain administrative tasks by
-performed by the Hyperledger GitHub organization administrators.
+performed by the LFDT GitHub organization administrators.
 
 In some repositories, the maintainers may decide to define additional scopes and
 each Maintainer given one or more of those designated scopes:
 
-- In rare cases, Maintainers in a repository may request that the Hyperledger Foundation GitHub organization administrators enable designating some Maintainers with different GitHub roles, such as "Admin" (more capable than "Maintain") or "Triage" (less capable than "Maintain").
-  - Each elevated GitHub role needed in a repository requires the Hyperledger Foundation GitHub organization administrators to create and maintain an additional GitHub Team.
-  - The Hyperledger Foundation GitHub organization administrators manage a team per Hyperledger Project that includes all contributors to the project. That team is given the "Read" GitHub role in all project repositories. This team need not be documented in the "MAINTAINERS" file.
+- In rare cases, Maintainers in a repository may request that the project's TSC enable designating some Maintainers with different GitHub roles, such as "Admin" (more capable than "Maintain") or "Triage" (less capable than "Maintain").
+  - Each elevated GitHub role needed in a repository requires the project's TSC to create and maintain an additional GitHub Team.
+  - The LFDT TAC manages a team per LFDT Project that includes all contributors to the project. That team is given the "Read" GitHub role in all project repositories. This team need not be documented in the "MAINTAINERS" file.
 - Maintainers **MAY** define Maintainer scopes within a repository that don't require
   elevated GitHub privileges. For example, a scope might include hosting
-  community meetings, or contributing to the Hyperledger Project's Quarterly
+  community meetings, or contributing to the LFDT Project's Quarterly
   report.
 
 If there is more than the single "Maintainer" scope used in a repository, there **MUST** be a list of the repository specific scopes in the MAINTAINERS file. The list must include the scope name, the definition of the scope, and if applicable, the related GitHub Role and Team for the scope.
@@ -51,13 +53,13 @@ If there is more than the single "Maintainer" scope used in a repository, there
 
 Lists of active and emeritus maintainers **MUST** be included in the `MAINTAINERS.md` file.
 
-Changes to the maintainers lists **MUST** be made via Pull Requests. Once a new `MAINTAINERS.md` file is created or a PR changing the maintainer lists within the file is merged, a corresponding update to the affected GitHub Teams within the Hyperledger GitHub organization must be made. This is a manual process and the maintainers must ensure that it occurs.
+Changes to the maintainers lists **MUST** be made via Pull Requests. Once a new `MAINTAINERS.md` file is created or a PR changing the maintainer lists within the file is merged, a corresponding update to the affected GitHub Teams within the LFDT GitHub organization must be made. This is a manual process and the maintainers must ensure that it occurs.
 
 It is recommended that the lists be sorted alphabetically and **MUST** contain at least the Maintainers name, GitHub ID, Scope, and at least one contact method. The reasons for populating columns are:
 
 - A GitHub ID **MUST** be provided to add the Maintainer to a GitHub Team, and to recognize the action the Maintainer takes in the repository.
 - The Scope **MUST** be provided to know the role of each Maintainer, and to know the GitHub Team to update when adding/removing Maintainers.
-- A LFID (Linux Foundation ID), Discord ID and/or Email are the most effective ways for the Hyperledger Foundation to contact the Maintainer when necessary.
+- A LFID (Linux Foundation ID), Discord ID and/or Email are the most effective ways for the LFDT to contact the Maintainer when necessary.
 - A Company Affiliation is helpful for monitoring the diversity of the Maintainer community for a project.
 
 The following table format **MUST** be used for both Maintainers lists (active and emeritus):

guidelines/SAMPLE-MAINTAINERS.md → governing-documents/SAMPLE-MAINTAINERS.md

@@ -7,13 +7,13 @@ nav_exclude: true
 [//]: # (SPDX-License-Identifier: CC-BY-4.0)
 # Maintainers
 
-This is a sample `MAINTAINERS.md` file for a Hyperledger project repository.
+This is a sample `MAINTAINERS.md` file for a Linux Foundation Decentralized Trust (LFDT) project repository.
 Feel free to copy this file into your repository and update it for your specific
 needs.
 
-It is sufficient to have a `MAINTAINERS.md` file that contains only a reference to a `MAINTAINERS.md` file in another repository that is part of the Hyperledger project.  For example:
+It is sufficient to have a `MAINTAINERS.md` file that contains only a reference to a `MAINTAINERS.md` file in another repository that is part of the LFDT project.  For example:
 
-> For information about the Maintainers of this repository, please see this Hyperledger \<PROJECT> repository's [MAINTAINERS](#) file.
+> For information about the Maintainers of this repository, please see this LFDT \<PROJECT> repository's [MAINTAINERS](#) file.
 
 ## Maintainer Scopes, GitHub Roles and GitHub Teams
 
@@ -57,9 +57,9 @@ Maintainers are expected to perform the following duties for this repository. Th
   give guidance and encouragement to those wanting to contribute to the product, and those wanting to become maintainers.
 - Contribute to the product via GitHub Pull Requests.
 - Monitor requests from the LF Decentralized Trust Technical Advisory Council about the
-contents and management of Hyperledger repositories, such as branch handling,
+contents and management of LFDT repositories, such as branch handling,
 required files in repositories and so on.
-- Contribute to the Hyperledger Project's Quarterly Report.
+- Contribute to the LFDT Project's Quarterly Report.
 
 ## Becoming a Maintainer
 
@@ -103,7 +103,7 @@ The process to move a maintainer from active to emeritus status is comparable to
 resignation, the Pull Request can be merged following a maintainer PR approval. If the removal is for any other reason, the following steps **SHOULD** be followed:
 
 - A PR is created to update this file to move the maintainer to the list of emeritus maintainers.
-- The PR is authored by, or has a comment supporting the proposal from, an existing maintainer or Hyperledger GitHub organization administrator.
+- The PR is authored by, or has a comment supporting the proposal from, an existing maintainer or a member of the project's Technical Steering Commitee (TSC).
 - Once the PR and necessary comments have been received, the approval timeframe begins.
 - The PR **MAY** be communicated on appropriate communication channels, including relevant community calls, chat channels and mailing lists.
 - The PR is merged and the maintainer transitions to maintainer emeritus if:

guidelines/repository-structure.md → governing-documents/repository-structure.md

@@ -1,13 +1,13 @@
 ---
 layout: default
 title: Common Repository Structure
-parent: Guidelines
+parent: Governing Documents
 grand_parent: LF Decentralized Trust TAC
 nav_order: 1
 ---
 # Common Repository Structure
 
-Hyperledger projects are required to maintain a standard set of files in each repository. This
+Linux Foundation Decentralized Trust (LFDT) projects are required to maintain a standard set of files in each repository. This
 document describes the required and recommended files.
 
 ## Required Files with Specified Content
@@ -17,7 +17,7 @@ link to the specified content with minimal exposition. These files MUST be at th
 repository.
 
 -   [`LICENSE`](https://www.apache.org/licenses/LICENSE-2.0.txt) - https://www.apache.org/licenses/LICENSE-2.0.txt\
-    (Unless an exception has been made by the Hyperledger Governing Board)
+    (Unless an exception has been made by the LFDT Governing Board)
 -   [`CODE_OF_CONDUCT.md`](https://tac.lfdecentralizedtrust.org/code-of-conduct.html) - https://tac.lfdecentralizedtrust.org/code-of-conduct.html
 -   [`SECURITY.md`](https://wiki.hyperledger.org/display/SEC/Defect+Response) - https://wiki.hyperledger.org/display/SEC/Defect+Response
 
@@ -32,31 +32,30 @@ format suffixes such as `.md`, `.rst`, or `.txt`.
     -   The current and important past releases
     -   Documentation for developers and users
 -   `MAINTAINERS` \
-    A list of all current maintainers with contact info. [A separate document](MAINTAINERS-guidelines.md)
+    A list of all current maintainers with contact info. [A separate document](MAINTAINERS-file.md)
     covers the specifics.
 -   `CONTRIBUTING` \
     Directions on how to contribute code to the project, or a pointer to the Wiki page with that information.
 -   `CHANGELOG` \
     A human readable list of recent changes. Changes should at least include the current release. This
     file may be maintainer curated or mechanically produced.
--   Continuous Integration / Continuous Delivery (CICD) configurations \
-    Configurations needed to run CICD on Hyperledger provided systems.
+-   Continuous Integration / Continuous Delivery (CI/CD) configurations \
+    Configurations needed to run CI/CD on LFDT Trust provided systems.
 
 ## Recommended
 
-Repositories SHOULD have these files. Named files SHOULD be at the root of the repository
+Repositories SHOULD have these files. Named files SHOULD be at the root of the repository.
 
 -   `NOTICE`
-    -   As per section 4 subsection d of the
+    -   As per section 4, subsection (d), of the
         [Apache License, Version 2](https://www.apache.org/licenses/LICENSE-2.0)
 -   Apache License Header information in each source code file. \
-    For new files added to Hyperledger repositories they SHOULD include the snippet `SPDX-License-Identifier: Apache-2.0` as part of the header. 
+    For new files added to LFDT repositories they SHOULD include the snippet `SPDX-License-Identifier: Apache-2.0` as part of the header.
     (see the [Copyright and Licencing Policy](https://wiki.hyperledger.org/display/TSC/Copyright+and+License+Policy))
 -   Build files consistent with the implementation language, such as...
     -   For JavaScript/Node.js a `package.json` file
     -   For Ruby a `Gemfile` file
-    -   For Java one of a Maven `pom.xml`, an Apache Ant `build.xml`, or a Gralde `build.gradle`
-        file
+    -   For Java, one of a Maven `pom.xml`, an Apache Ant `build.xml`, or a Gradle `build.gradle`, file
     -   For Python `setup.py` and `requirements.txt` files
     -   For Go `go.mod` and optionally `go.sum` 
     -   For Rust a `cargo.toml` file
@@ -69,7 +68,7 @@ Repositories SHOULD have these files. Named files SHOULD be at the root of the r
 
 ## Prohibited
 
-Repositories MUST NOT have these files
+Repositories MUST NOT have these files.
 
 -   Executable binaries and shared library files built by code in the repository \
     This includes `.exe`, `.dll`, `.so`, `.a` and `.dylib` files not otherwise part of a third party
@@ -78,5 +77,6 @@ Repositories MUST NOT have these files
 # Tooling
 
 In order to help automate checks a repolinter file and supporting scripts can be found in
-[Hyperledger Community Management Tools](https://github.com/hyperledger-labs/hyperledger-community-management-tools/tree/main/repo_structure).
-Note that where the two repositories and tooling differ this document takes precedence.
+[LFDT Community Management Tools](https://github.com/hyperledger-labs/hyperledger-community-management-tools/tree/main/repo_structure).
+
+Note that this document takes precedence over documents in the folder linked above, wherever the instructions and tooling differ between the two.

guidelines/project-best-practices.md

@@ -44,12 +44,12 @@ The [Project Incubation Exit Criteria](../governing-documents/project-incubation
 
 ## Repository structure
 
-* Projects should follow the [Common Repository Structure](repository-structure.md) which provides details for required and recommended repository files.
+* Projects should follow the [Common Repository Structure](../governing-documents/repository-structure.md) which provides details for required and recommended repository files.
 
 ## Maintainer guidelines
 
-* Projects should document maintainers along with maintainer roles and responsibilities in a MAINTAINERS.md file.
-* See the [Maintainers Guidelines](MAINTAINERS-guidelines.md) and [sample MAINTAINERS.md](SAMPLE-MAINTAINERS.md) for suggested duties of a maintainer and guidance on how to add and remove maintainers.
+* Projects should document maintainers along with maintainer roles and responsibilities in a `MAINTAINERS.md` file.
+* See the [Maintainers File Governing Document](../governing-documents/MAINTAINERS-file.md) and [sample MAINTAINERS.md](../governing-documents/SAMPLE-MAINTAINERS.md) for suggested duties of a maintainer and guidance on how to add and remove maintainers.
 
 ## Inclusive naming
 
@@ -170,9 +170,9 @@ The [Project Incubation Exit Criteria](../governing-documents/project-incubation
 ## GitHub configuration
 
 * Define repository settings in `.github/settings.yml` so that they can be managed and tracked via pull requests, see [Fabric example](https://github.com/hyperledger/fabric/blob/main/.github/settings.yml).
-* Consider using a CODEOWNERS file to specify write permission per directory
+* Consider using a `CODEOWNERS` file to specify write permission per directory
   - See [Fabric example](https://github.com/hyperledger/fabric/blob/main/CODEOWNERS) with additional `/docs` maintainers.
-  - Add a link from CODEOWNERS to MAINTAINERS.md scope field so that users can find domain area contacts
+  - Add a link from `CODEOWNERS` to `MAINTAINERS.md` scope field so that users can find domain area contacts
 * Consider using a .github/[PULL_REQUEST_TEMPLATE.md](https://raw.githubusercontent.com/hyperledger/fabric/main/.github/PULL_REQUEST_TEMPLATE.md) and .github/[ISSUE_TEMPLATE](https://github.com/hyperledger/fabric/tree/main/.github/ISSUE_TEMPLATE)
 * Define Branch protection rules. Recommended configuration:
   - Check `Require a pull request before merging`

project-reports/0000-annual-review-template.md

@@ -14,7 +14,7 @@ nav_exclude: true
 </mark>
 
 # Maintainer Diversity
-<mark>_How many maintainers do you have, and which organisations are they from? How has the maintainers and diversity of your maintainers changed in the past year? Has the number of active maintainers increased/decreased? Has the diversity of maintainers increased/decreased? Please include a link to your existing [MAINTAINERS file](../guidelines/MAINTAINERS-guidelines.md) and the MAINTAINERS file from last year (if appropriate). This is a good opportunity to ensure that your MAINTAINERS file is up to date and to retire any maintainers._ 
+<mark>_How many maintainers do you have, and which organisations are they from? How has the maintainers and diversity of your maintainers changed in the past year? Has the number of active maintainers increased/decreased? Has the diversity of maintainers increased/decreased? Please include a link to your existing [MAINTAINERS file](../governing-documents/MAINTAINERS-file.md) and the MAINTAINERS file from last year (if appropriate). This is a good opportunity to ensure that your MAINTAINERS file is up to date and to retire any maintainers._
 </mark>
 
 # Project Adoption

project-reports/2023/2023-Q1-Hyperledger-Besu.md

@@ -14,7 +14,7 @@ Additionally, with Shanghai enabling Ether withdrawals from validators, HLF can
 All completed for Besu. 
 
 - Have you switched from master to main in all your repos?
-- Have you implemented the [Common Repository Structure](../guidelines/repository-structure.md) in all your repos?
+- Have you implemented the [Common Repository Structure](../../governing-documents/repository-structure.md) in all your repos?
 - Has your project implemented these inclusive language changes listed below to your repo? You can optionally [use the DCI Lint tool](https://github.com/petermetz/gh-action-dci-lint#usage) to make this a recurring action on your repo.
   - master → main
   - slave → replicas

project-reports/2023/2023-Q1-Hyperledger-Caliper.md

@@ -15,7 +15,7 @@ grand_parent: Project Updates
 # Required Information
 
 - Have you switched from master to main in all your repos? __Yes.__
-- Have you implemented the [Common Repository Structure](../guidelines/repository-structure.md) in all your repos? __Yes.__
+- Have you implemented the [Common Repository Structure](../../governing-documents/repository-structure.md) in all your repos? __Yes.__
 - Has your project implemented these inclusive language changes listed below to your repo? You can optionally [use the DCI Lint tool](https://github.com/petermetz/gh-action-dci-lint#usage) to make this a recurring action on your repo. __Yes.__
   - master → main
   - slave → replicas

project-reports/2023/2023-Q1-Hyperledger-Cello.md

@@ -17,7 +17,7 @@ The 1.0 release is with new architecture.
 
 # Required Information
 - [x] Have you switched from master to main in all your repos? 
-- [x] Have you implemented the [Common Repository Structure](../guidelines/repository-structure.md) in all your repos? 
+- [x] Have you implemented the [Common Repository Structure](../../governing-documents/repository-structure.md) in all your repos? 
 - [x] Has your project implemented these inclusive language changes listed below to your repo? You can optionally [use the DCI Lint tool](https://github.com/petermetz/gh-action-dci-lint#usage) to make this a recurring action on your repo.
     - master → main
     - slave → replicas

project-reports/2023/2023-Q1-Hyperledger-FireFly.md

@@ -20,7 +20,7 @@ There are currently 640k lines of code for Hyperledger FireFly across 19 reposit
 # Required Information
 
 - Have you switched from master to main in all your repos? Yes
-- Have you implemented the [Common Repository Structure](../guidelines/repository-structure.md) in all your repos? Yes
+- Have you implemented the [Common Repository Structure](../../governing-documents/repository-structure.md) in all your repos? Yes
 - Has your project implemented these inclusive language changes listed below to your repo? You can optionally [use the DCI Lint tool](https://github.com/petermetz/gh-action-dci-lint#usage) to make this a recurring action on your repo. Yes
   - master → main
   - slave → replicas

project-reports/2023/2023-Q1-Hyperledger-Sawtooth.md

@@ -14,7 +14,7 @@ discussions about simplifying the build processes.
 
 - Have you switched from master to main in all your repos? YEs
 - Have you implemented the [Common Repository
-  Structure](../guidelines/repository-structure.md) in all your repos? Yes
+  Structure](../../governing-documents/repository-structure.md) in all your repos? Yes
 - Has your project implemented these inclusive language changes listed below to
   your repo? You can optionally [use the DCI Lint
   tool](https://github.com/petermetz/gh-action-dci-lint#usage) to make this a