google / pull-request-mailer Goto Github PK

View Code? Open in Web Editor NEW

44.0 12.0 15.0 265 KB

Sends a GitHub pull request as a patch series via email

License: BSD 3-Clause "New" or "Revised" License

Haskell 100.00%

pull-request-mailer's Introduction

pull-request-mailer

Sends a GitHub pull request as a patch series via email

Disclaimer: This is not an official Google product.

Many open-source projects (such as the Linux kernel or the Ganeti project) accept patches only via their mailing lists.

This tool makes it easy to integrate contributors who prefer Github pull requests into mailing list review workflows.

Features

Sending a pull request to a mailing list takes no more than 1 command.
Optional notification as a pull request comment that discussion shall be continued on the mailing list (instead of in the pull request).
Support for force-pushes and thread tracking. After addressing review feedback, the improved patches can be force-pushed into the pull request, and the next invocation of this tool will send the next patch series as a reply to the previous email thread.
Optionally it's possible to run the tool in daemon mode, let it receive GitHub webhooks and automatically process them.

Usage

Procesing a single pull request

Usage: pull-request-mailer USER REPO N --to EMAIL [--post-checkout-hook PROGRAM]
                           [--no-thread-tracking] [--discussion-location STRING]
  Sends a GitHub pull request as a patch series via email

Available options:
  -h,--help                Show this help text
  USER                     GitHub user who owns the repo containing the pull
                           request
  REPO                     Repo containing the pull request
  N                        Number of the pull request
  --to EMAIL               Email recipient
  --post-checkout-hook PROGRAM
                           A program in the cloned direcotry just after checkout
  --no-thread-tracking     Disable posting thread message ID and patch iteration
                           count into the pull request. When active, future
                           versions of the PR can not be sent as reply to the
                           created email thread
  --discussion-location STRING
                           The place where the contents of the PR are discussed
                           (as opposed to the discussion being in PR comments.
                           Example: 'the mailing list [email protected]'.

Available environment variables:
  PULL_REQUEST_MAILER_OAUTH_TOKEN
                           Auth token needed to write information into the pull
                           request. You can generate one at
                           https://github.com/settings/applications.
  PULL_REQUEST_MAILER_SECRET_TOKEN
                           Secret token to verify that requests really come from
                           Github. See
                           https://developer.github.com/webhooks/securing.

Automated server mode

Usage: pull-request-mailer-server --to EMAIL [--post-checkout-hook PROGRAM]
                                  [--no-thread-tracking]
                                  [--discussion-location STRING]
  Receive GitHub pull request webbooks and send the patch series via email

Available options:
  -h,--help                Show this help text
  --to EMAIL               Email recipient
  --post-checkout-hook PROGRAM
                           A program in the cloned direcotry just after checkout
  --no-thread-tracking     Disable posting thread message ID and patch iteration
                           count into the pull request. When active, future
                           versions of the PR can not be sent as reply to the
                           created email thread
  --discussion-location STRING
                           The place where the contents of the PR are discussed
                           (as opposed to the discussion being in PR comments.
                           Example: 'the mailing list [email protected]'.

Available environment variables:
  PULL_REQUEST_MAILER_OAUTH_TOKEN
                           Auth token needed to write information into the pull
                           request. You can generate one at
                           https://github.com/settings/applications.
  PULL_REQUEST_MAILER_SECRET_TOKEN
                           Secret token to verify that requests really come from
                           Github. See
                           https://developer.github.com/webhooks/securing.

Contact

The tool has been created and is maintained by the Ganeti team. Please send any questions to the [email protected] mailing list (also available online).

pull-request-mailer's People

Contributors

Stargazers

Watchers

Forkers

nh2 abartlet linearregression muvarov gnusosa neotim isabella232 ghas-results

pull-request-mailer's Issues

Use environment variables for passing credentials, instead of command line arguments

Add the author's name to the originating email address

Currently it's not possible to see who authored a series from the sender's email address. Would it be possible to add the author's name, so that it looks something like Joe Programmer [email protected]?

Switch the 'scotty' library to production mode

Currently it's running in it's default debugging mode. See the header of the module description.

Warn on missing signed-off-by

When sending a PATCH email, it would be useful to have a warning when signed-off-by was forgotten.

This warning need not be shown for RFC emails.

Rename modules from Emailer to Mailer

Since the project is called pull-request-mailer.

Fork before clone in server

We cd into the cloned directory, which is fine for the command line utility, but not for the server (its process should stay in the same directory).

Thus we need to forkProcess before executing pull-request-mailer commands. (It must not be forkOS as this only creates a new thread, not a new process.)

Otherwise, we get fatal: Could not get current working directory: No such file or directory.

Option to use request-pull

It would be nice if there were an option to use request-pull -p instead of format-patch

Safe-guard number of patches to be sent

We should add an option for this, e.g. if somebody sends > 1000 patches, probably something is wrong.

Limit the amount of received data with each webhook request

Just to prevent DoS attacks, making the server eating too much memory.

Produce interdiffs for subsequent modifications of a pull request

For a large patch series it's very inconvenient to look for changes between the old and the new version.
@aehlig

hGetContents: invalid argument (invalid byte sequence)

When running pull-request-mailer-server on ganeti/ganeti#16, it failed with:

pull-request-mailer-server: patch-dir/0000-cover-letter.patch: hGetContents: invalid argument (invalid byte sequence)

Root cause is probably an encoding problem, likely in the UTF8 author name in the commit (see https://github.com/nh2/ganeti/commit/48770897db31d6ffc08b7488dd75f31a020e337c.patch).

Cabal has had this problem, and same for hlint. An explanation can be found here:

This is caused by relying on System.IO.readFile to infer the text-encoding, instead of explicitly setting it to utf8.

Processing the problematic PR locally on a different machine with pull-request-mailer worked, most likely because there the LANG environment variable was set to something, e.g. en_US.UTF-8, while on the problematic server it was not set (or set to the empty string).

You can reproduce it like this:

LANG="" pull-request-mailer --discussion-location='somewhere else' --to [email protected] --no-thread-tracking ganeti ganeti 16

The solution should be either instructing the user to set LANG or check if git format-patch outputs UTF-8 by default and explicitly specify that encoding when reading the cover letter.

Customizable patch type (PATCH,RFC)

It would be nice to allow sending RFC emails instead of only PATCH emails.

Repository cache

We could use git clone --reference to speed up clones.

This would be especially important for large git projects, e.g. Android.

It is even possible to cache multiple different remotes in one bare "cache repository", as explained in http://randyfay.com/content/reference-cache-repositories-speed-clones-git-clone-reference

Since our clones are only temporary, the common pitfalls of --reference (referenced repository going away) are not a problem for us.

We would, however, have to make sure not to clean the cache (if we implement cache cleaning) while a clone or other git actions are happening.

Payload secret validation of webhook

The newer version of the github package already has something for that.

Add instructions for git config and email for the server

We should remind users to git config user name and email and set up their mail server before they run the pull-request-mailer server.