TianoCore GitHub Email Archive Webhook Service

Assign reviewers to commits in a GitHub pull request based on assignments documented in Maintainers.txt and generates an email archive of all pull request and code review activities.

Webhook Service Command Line Options

usage: Server [-h] [-e {Off,SMTP,SendGrid}] [-v] [-q] [--debug [0-9]]

Assign reviewers to commits in a GitHub pull request based on assignments
documented in Maintainers.txt and generate email archive of all review
activities. Copyright (c) 2020, Intel Corporation. All rights reserved.

optional arguments:
  -h, --help            show this help message and exit
  -e {Off,SMTP,SendGrid}, --email-server {Off,SMTP,SendGrid}
                        Email server type used to send emails.
  -v, --verbose         Increase output messages
  -q, --quiet           Reduce output messages
  --debug [0-9]         Set debug level

System Environment Variables

The following environment variables must be set before starting the webhook service.

• GITHUB_TOKEN - 40 character hex string that is a Personal Access Token created in GitHub in User->Settings->Developer Settings->Personal access tokens. The personal access token must be generated from a user account that has permissions to the GitHub repositories for which an email archive is required. This token is used by the webhook service when making GitHub API calls. If this environment variable is not set correctly then GitHub API calls fail.

  Creating webHooks

• GITHUB_WEBHOOK_SECRET - 64 character hex string that is secret used to validate payloads received from GitHub. If this envirionment variable is not set correctly, then all payloads from GitHub are rejected. This value must match the GitHub repository setting in Settings->WebHooks->Edit->Secret.

  Setting your secret token

• GITHUB_WEBHOOK_ROUTE - The route the webhook server listens for payloads sent by GitHub (e.g. /webhook). This value must match the GitHub repository setting Settings->WebHooks->Edit->Payload URL.

• GITHUB_WEBHOOK_PORT_NUMBER - The port the webhook server listens for payloads sent by GitHub (e.g. 8888). This value must match the GitHub repository setting Settings->WebHooks->Edit->Payload URL.

• GITHUB_REPO_WHITE_LIST - A list of repositories from a single GitHub account that the webhook service supports. The format of this setting is a Python list of strings with each string containing the GitHub account name '/' then the GitHub repository name (e.g. ['mdkinney/repo1', 'mdkinney/repo1']).

• EMAIL_ARCHIVE_ADDRESS - The TO address for emails address generated by this webhook service. This is typically the address of an email subscription service that allows a community of developers to receive the emails generated by this webhook service and for the emails to be archived.

• SMTP_ADDRESS - The address of the SMTP server used to send emails (e.g. smtp.gmail.com).

• SMTP_PORT_NUMBER - The port number of the SMTP server used to send emails (e.g. 587).

• SMTP_USER_NAME - The use name of the account on the SMTP server used to send emails.

• SMTP_PASSWORD - The password of the account on the SMTP server used to send emails.

• SENDGRID_API_KEY - The API key used to send emails using SendGrid. The webook service can use either use an SMTP server or SendGrid to send emails using a command line flag to select one of these options.

Maintainers.txt File Format

The file Maintainers.txt must be present in the root of a repository.

The following describe the syntax of a section statement. If a line does not start with one of the tags listed below, then the line is considered a section separator. Blank lines and end of file are also section separators.

• L: Mailing list that is relevant to this area (default is edk2-devel) Patches and questions should be sent to the email list.
• M: Package Maintainer: Cc address for patches and questions. Responsible for reviewing and pushing package changes to source control. The end of this line must contain the GitHub ID of the maintainer in [].
• R: Package Reviewer: Cc address for patches and questions. Reviewers help maintainers review code, but don't have push access. A designated Package Reviewer is reasonably familiar with the Package (or some modules thereof), and/or provides testing or regression testing for the Package (or some modules thereof), in certain platforms and environments. The end of this line must contain the GitHub ID of the maintainer in [].
• W: Web-page with status/info
• T: SCM tree type and location. Type is one of: git, svn.
• S: Status, one of the following:
  • Supported: Someone is actually paid to look after this.
  • Maintained: Someone actually looks after it.
  • Odd Fixes: It has a maintainer but they don't have time to do much other than throw the odd patch in. See below.
  • Orphan: No current maintainer [but maybe you could take the role as you write your new code].
  • Obsolete: Old code. Something tagged obsolete generally means it has been replaced by a better system and you should be using that.
• F: Files and directories with wildcard patterns. A trailing slash includes all files and subdirectory files. One pattern per line. Multiple F: lines per section acceptable.
  • F: MdeModulePkg/ all files in and below MdeModulePkg
  • F: MdeModulePkg/* all files in MdeModulePkg, but not below
  • F: */Pci/* all files in a directory called Pci, at any depth in the hierarchy, but not below
• X: Files and directories that are NOT maintained, same rules as F: Files exclusions are tested after file matches. Can be useful for excluding a specific subdirectory. The example below matches all files in and below NetworkPkg excluding NetworkPkg/Ip6Dxe/.

F: NetworkPkg/
X: NetworkPkg/Ip6Dxe/

Filenames not caught by any F: rule get matched as being located in the top- level directory. (Internally, the script looks for a match called <default>, so please don't add a file called that in the top-level directory.)

Webhook Event Processing

Unit Tests

Build Status

License Details

The majority of the content in the EDK II open source project uses a BSD-2-Clause Plus Patent License.

The EDK II Project is composed of packages. The maintainers for each package are listed in Maintainers.txt.

Resources

• TianoCore
• EDK II
• Getting Started with EDK II
• Mailing Lists
• TianoCore Bugzilla
• How To Contribute
• Release Planning

Code Contributions

To make a contribution to a TianoCore project, follow these steps.

1. Create a change description in the format specified below to use in the source control commit log.

2. Your commit message must include your Signed-off-by signature

3. Submit your code to the TianoCore project using the process that the project documents on its web page. If the process is not documented, then submit the code on development email list for the project.

4. It is preferred that contributions are submitted using the same copyright license as the base project. When that is not possible, then contributions using the following licenses can be accepted:

   • BSD (2-clause): http://opensource.org/licenses/BSD-2-Clause
   • BSD (3-clause): http://opensource.org/licenses/BSD-3-Clause
   • MIT: http://opensource.org/licenses/MIT
   • Python-2.0: http://opensource.org/licenses/Python-2.0
   • Zlib: http://opensource.org/licenses/Zlib

   For documentation:

   • FreeBSD Documentation License https://www.freebsd.org/copyright/freebsd-doc-license.html

   Contributions of code put into the public domain can also be accepted.

   Contributions using other licenses might be accepted, but further review will be required.

Developer Certificate of Origin

Your change description should use the standard format for a commit message, and must include your Signed-off-by signature.

In order to keep track of who did what, all patches contributed must include a statement that to the best of the contributor's knowledge they have the right to contribute it under the specified license.

The test for this is as specified in the Developer's Certificate of Origin (DCO) 1.1. The contributor certifies compliance by adding a line saying

Signed-off-by: Developer Name [email protected]

where Developer Name is the contributor's real name, and the email address is one the developer is reachable through at the time of contributing.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

Sample Change Description / Commit Message

From: Contributor Name <[email protected]>
Subject: [Repository/Branch PATCH] Pkg-Module: Brief-single-line-summary

Full-commit-message

Signed-off-by: Contributor Name <[email protected]>

Notes for sample patch email

• The first line of commit message is taken from the email's subject line following [Repository/Branch PATCH]. The remaining portion of the commit message is the email's content.
• git format-patch is one way to create this format

Definitions for sample patch email

• Repository is the identifier of the repository the patch applies. This identifier should only be provided for repositories other than edk2. For example edk2-BuildSpecification or staging.
• Branch is the identifier of the branch the patch applies. This identifier should only be provided for branches other than edk2/master. For example edk2/UDK2015, edk2-BuildSpecification/release/1.27, or staging/edk2-test.
• Module is a short identifier for the affected code or documentation. For example MdePkg, MdeModulePkg/UsbBusDxe, Introduction, or EDK II INF File Format.
• Brief-single-line-summary is a short summary of the change.
• The entire first line should be less than ~70 characters.
• Full-commit-message a verbose multiple line comment describing the change. Each line should be less than ~70 characters.
• Signed-off-by is the contributor's signature identifying them by their real/legal name and their email address.