diff --git a/guidelines/MAINTAINERS-guidelines.md b/governing-documents/MAINTAINERS-guidelines.md similarity index 81% rename from guidelines/MAINTAINERS-guidelines.md rename to governing-documents/MAINTAINERS-guidelines.md index f6bacf6d..1dccf6bb 100644 --- a/guidelines/MAINTAINERS-guidelines.md +++ b/governing-documents/MAINTAINERS-guidelines.md @@ -1,7 +1,7 @@ --- layout: default title: MAINTAINERS Guidelines -parent: Guidelines +parent: Governing Documents grand_parent: LF Decentralized Trust TAC nav_order: 2 --- @@ -9,9 +9,9 @@ nav_order: 2 ## 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 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 +28,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 LFDT TAC 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 LFDT GitHub organization administrators 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 +51,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): diff --git a/guidelines/SAMPLE-MAINTAINERS.md b/governing-documents/SAMPLE-MAINTAINERS.md similarity index 93% rename from guidelines/SAMPLE-MAINTAINERS.md rename to governing-documents/SAMPLE-MAINTAINERS.md index cbdd480a..78e8e41d 100644 --- a/guidelines/SAMPLE-MAINTAINERS.md +++ b/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 \ repository's [MAINTAINERS](#) file. +> For information about the Maintainers of this repository, please see this LFDT \ 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 LFDT GitHub organization administrator (i.e., TAC). - 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: diff --git a/guidelines/repository-structure.md b/governing-documents/repository-structure.md similarity index 75% rename from guidelines/repository-structure.md rename to governing-documents/repository-structure.md index 9dbf3de5..701f67ce 100644 --- a/guidelines/repository-structure.md +++ b/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 @@ -39,24 +39,23 @@ format suffixes such as `.md`, `.rst`, or `.txt`. - `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. diff --git a/guidelines/project-best-practices.md b/guidelines/project-best-practices.md index e76f7d59..312a96c8 100644 --- a/guidelines/project-best-practices.md +++ b/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 Guidelines](../governing-documents/MAINTAINERS-guidelines.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` diff --git a/project-reports/0000-annual-review-template.md b/project-reports/0000-annual-review-template.md index 9130f5d4..f64c06c5 100644 --- a/project-reports/0000-annual-review-template.md +++ b/project-reports/0000-annual-review-template.md @@ -14,7 +14,7 @@ nav_exclude: true # Maintainer Diversity -_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._ +_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-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._ # Project Adoption diff --git a/project-reports/2023/2023-Q1-Hyperledger-Besu.md b/project-reports/2023/2023-Q1-Hyperledger-Besu.md index 8f565470..f5999c38 100644 --- a/project-reports/2023/2023-Q1-Hyperledger-Besu.md +++ b/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 diff --git a/project-reports/2023/2023-Q1-Hyperledger-Caliper.md b/project-reports/2023/2023-Q1-Hyperledger-Caliper.md index 2a2e9c88..60f6707a 100644 --- a/project-reports/2023/2023-Q1-Hyperledger-Caliper.md +++ b/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 diff --git a/project-reports/2023/2023-Q1-Hyperledger-Cello.md b/project-reports/2023/2023-Q1-Hyperledger-Cello.md index db88d7d4..c35c0de9 100644 --- a/project-reports/2023/2023-Q1-Hyperledger-Cello.md +++ b/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 diff --git a/project-reports/2023/2023-Q1-Hyperledger-FireFly.md b/project-reports/2023/2023-Q1-Hyperledger-FireFly.md index e7784b41..6f70703b 100644 --- a/project-reports/2023/2023-Q1-Hyperledger-FireFly.md +++ b/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 diff --git a/project-reports/2023/2023-Q1-Hyperledger-Sawtooth.md b/project-reports/2023/2023-Q1-Hyperledger-Sawtooth.md index 77ba1438..e051c345 100644 --- a/project-reports/2023/2023-Q1-Hyperledger-Sawtooth.md +++ b/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 diff --git a/project-reports/2023/2023-Q1-Hyperledger-Solang.md b/project-reports/2023/2023-Q1-Hyperledger-Solang.md index 7a89a5c6..76304102 100644 --- a/project-reports/2023/2023-Q1-Hyperledger-Solang.md +++ b/project-reports/2023/2023-Q1-Hyperledger-Solang.md @@ -14,7 +14,7 @@ helping users and fixing bugs as they arise. # 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? **Only the main solang repo** +- Have you implemented the [Common Repository Structure](../../governing-documents/repository-structure.md) in all your repos? **Only the main solang repo** - 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 @@ -67,4 +67,4 @@ Salaheldin Soliman, last years Hyperledger Mentee, continues to make great contr # Additional Information -None at this time. \ No newline at end of file +None at this time. diff --git a/project-reports/2024/2024-annual-Hyperledger-Aries.md b/project-reports/2024/2024-annual-Hyperledger-Aries.md index 910700d5..8e91e18e 100644 --- a/project-reports/2024/2024-annual-Hyperledger-Aries.md +++ b/project-reports/2024/2024-annual-Hyperledger-Aries.md @@ -23,7 +23,7 @@ Aries remains a healthy project and one of several viable candidates for major d ## Maintainer Diversity -_Guidance: 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](https://github.com/hyperledger/toc/blob/gh-pages/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._ +_Guidance: 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](https://github.com/hyperledger/toc/blob/gh-pages/governing-documents/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._ There are currently 62 people on the 48 Hyperledger Aries teams representing at least 19 organizations. As there are still dependent projects in Hyperledger, the Agent Framework JavaScript Maintainers continue to be Aries Maintainers, despite the move of the repository to the Open Wallet Foundation.