Status

RESOLVED 

OutcomeUnanimously approved
Minutes Link2020 02 13 TSC Minutes

Note: This decision was amended by End requirement to use Repolinter and a textual definition of the common repository structure is now available: https://tsc.hyperledger.org/repository-structure.html

Overview of Proposal

Hyperledger would benefit from a common repo structure which presents the same elements consistently. This includes:

  • README
  • SECURITY
  • CODEOWNERS
  • CODE_OF_CONDUCT
  • CONTRIBUTING
  • LICENSE
  • MAINTAINERS
  • NOTICES

Formal Proposal(s)

Adopt repolinter with a policy as in Fabric PR#630. Each repo will add the same repolint.json file and the CA team (or preferably CI) will periodically run a check to ensure projects are in compliance. Additionally, we should establish a template repository that has LICENSE, NOTICE, CoC and Security default files.

$ npx repolinter ../hyperledger/fabric
npx: installed 60 in 3.726s
Target directory: /Users/cbf/dev/hyperledger/fabric
Ruleset: repolint.json
Linguist Axiom: Linguist not found in path, only running language-independent rules
Target directory: /Users/cbf/dev/hyperledger/fabric
✔ notice-file-exists: found (NOTICE)
✔ license-file-exists: found (LICENSE)
✔ readme-file-exists: found (README.md)
✔ contributing-file-exists: found (CONTRIBUTING.md)
✔ code-of-conduct-file-exists: found (CODE_OF_CONDUCT.md)
✔ changelog-file-exists: found (CHANGELOG.md)
✔ security-file-exists: found (SECURITY.md)
⚠ support-file-exists: not found: ({docs/,.github/,}SUPPORT*)
✔ readme-references-license: File README.md contains license
✔ binaries-not-present: Excluded file type doesn't exist (**/*.exe,**/*.dll,!node_modules/**)
✔ test-directory-exists: found (test-pyramid.png)
✔ integrates-with-ci: found (.github/workflows/trigger.yml)
⚠ code-of-conduct-file-contains-email: File CODE_OF_CONDUCT.md doesn't contain email address
⚠ github-issue-template-exists: not found: (ISSUE_TEMPLATE*, .github/ISSUE_TEMPLATE*)
✔ github-pull-request-template-exists: found (.github/PULL_REQUEST_TEMPLATE.md)
✔ license-detectable-by-licensee: Licensee identified the license for project: Apache-2.0

Action Items

  • Type your task here, using "@" to assign to a user and "//" to select a due date

Reviewed By

17 Comments

  1. Christopher Ferris

    We should probably also document formally the Copyright and License markup expectations, and we should stipulate the content of CODE_OF_CONDUCT, LICENSE and SECURITY. It would also be ideal to recommend a format for MAINTAINERS so that we might a) automate addition to mailing list and b) ensure people can be easily found online (email, chat, GH etc).

    1. Tracy Kuhrt

      This is what was previously discussed and recommended by The Linux Foundation regarding copyright and license: Copyright and License Policy

    2. Dan Middleton

      Regarding MAINTAINERS.md format, LFID was recommended as an identifying field so that staff can find us across different platforms. 

  2. Christopher Ferris

    I might suggest a template repo where we could as the TSC manage any changes over time.

    1. Ry Jones

      I played with this - if you use a template repo, you have to force push to master to fix the DCO. Better to use a GitHub action, which I’m working on

      1. Christopher Ferris

        I wasn't thinking a formal template as much as one that should be emulated, but where we track changes to the recommended structure via Git

        1. Ry Jones

          I misunderstood.

          1. Christopher Ferris

            no worries.

  3. David Huseby

    My 2p:

    • We should format files with an eye towards automation. Whatever we put in each file we need to ask ourselves, should the content be easy to consume from a script? Should it be autogenerated periodically?
    • I'm unclear as to the difference between CODEOWNERS and MAINTAINERS.
      • Is CODEOWNERS all of the contributors? The contributors can be calculated from the Git history although the email addresses used in Git repos don't always map to real people.
    • Eventually we want to store identity/key material "in-band" with the repo itself and then require that all contributions be digitally signed by an identity/key that is already in the repo. This would give us airtight provenance for DCO and knowing who can vote.
      • Once we make this move, we can require contributors land PR's to add their identity/key material in the repo before contributing code. This initial PR should include a digital signature over the CODE_OF_CONDUCT and the GOVERNANCE document and any other documents we require contributors to agree to.
    • Do we want a GOVERNANCE document that specifies who is a MAINTAINER and how the list of maintainers is updated and when?

    1. Ry Jones

      CODEOWNERS is "people who would like to review changes in a specific place". MAINTAINERS may be people that are not interested in reviewing changes - CODEOWNERS is far more granular, down to single files, for instance.

    2. Hart Montgomery

      Yes, we should definitely think about automation for whatever we do here.  Your and Chris's ideas seem to be in the same vein here, and hopefully we can do this in a way that makes it easy to automate information gathering on this stuff.

  4. Christopher Ferris

    I'm somewhat delinquent because we never got a call together. Maybe we take this in stages. The first stage being what files we require and how they are formatted. The repo-linter tool takes us part way there.

    1. Gari Singh

      minimally we should require files that will be useful for enforcing / checking legal, compliance and governance issues

  5. Dan Middleton

    Link to Task Force page: Repository Structure Task Force

  6. Arnaud J Le Hors

    I updated this issue to capture the recommendation from the Task Force.

  7. Arun S M

    Note: The fabric PR mentioned in here is closed. Caliper has it https://github.com/hyperledger/caliper/blob/master/repolint.json.

    1. Arnaud J Le Hors

      I think it's better to use as a reference: https://github.com/hyperledger-labs/hyperledger-community-management-tools/blob/main/repo_structure/repolint.json