Eli Bendersky's website - Version control

GitHub Actions: first impressions

2020-09-25T20:13:00-07:00

I've been using Travis CI fairly extensively since 2013, when I moved my personal OSS projects from Bitbucket to GitHub. It's a great service and a much-appreciated boon to the open-source community.

However, since Travis announced that their .org variant is shutting down soon, I wanted to check out some of the alternatives, and GitHub actions (GHA) seemed very interesting.

So this week I've migrated pycparser and a few of my other OSS projects over to GHA. This turned out to be very easy! Here's a brief recap.

Workflow configuration

To activate GHA for pycparser, all I had to do is create the following YAML file as .github/workflows/ci.yml in the repository:

name: pycparser-tests
on:
  push:
    branches:
      - master
  pull_request:
    branches:
      - master

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        python-version: [2.7, 3.6, 3.7, 3.8]
        os: [ubuntu-latest, macos-latest, windows-latest]

    steps:

    - uses: actions/checkout@v2
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v2
      with:
        python-version: ${{ matrix.python-version }}
    - name: Test
      run: |
        python tests/all_tests.py

Some notes:

This workflow fires on two kinds of events: pushes to the master branch and PRs to the master branch. Each PR will have an automatic CI run for each change (every new commit pushed).
It runs in multiple configurations: the cross-product of Python versions and OSes, as specified.
The run: entry is the command the runs the tests.
While pycparser doesn't have any dependencies, it's easy to have those too by adding pip install $whatever lines to run: before the actual test execution line.

GitHub tests passed badge

First impressions

My first impressions of GHA compared to Travis:

Actions run much faster; the CI jobs schedule pretty much immediately. On Travis you might have to wait for multiple minutes.
Out-of-the-box Windows and Mac OS option! I couldn't get these with the free Travis variant and had to augment my CI solution for pycparser by running on Windows through AppVeyor. Now I only need to maintain a single CI workflow.
Travis seems to have better documentation and configurability at this point; while the GHA documentation is comprehensive, it's a bit scattered and harder to follow. This is something I hope will improve over time.

I like what I'm seeing from GHA so far; the ability to set up a CI workflow very easily without bouncing between multiple Web UIs is a blessing, and GHA appears to be a capable, performant platform with a convenient selection of OSes.

I'm still using Travis for some projects and will continue comparing the two over the coming months.

How to send good pull requests on GitHub

2019-11-06T06:15:00-08:00

Over the past few years I authored or reviewed thousands of GitHub pull requests (PRs), both for work and for personal projects. I've come to believe there's a small set of useful rules of thumb for what makes a good PR, what makes a bad PR, and why getting the good ones merged is much easier - both for the PR author and the reviewer.

Here's a quick checklist for a good PR. Each item is described in more detail below.

Make sure the PR is needed
Have an open issue linked in (optional)
Write a useful PR title
Write a detailed PR description
Adhere to the project's coding standards
Add tests
Make sure all tests pass
Be patient and friendly during code review

Make sure the PR is needed

This is especially important if you're contributing to a repository you haven't worked with much before. Do some research in the existing issues and PRs in the repository - including closed ones. Is this change already being discussed somewhere? Was it proposed before and rejected? The code you want to change - is it there for a good reason?

GitHub offers reasonably good search capabilities in case the project has a large log of issues in PRs. It's not perfect, but by running a few searches with probable keywords there's a good chance to find something. Another thing I often do is search the commit history of a project for relevant information (git log --grep).

Demonstrating some due diligence goes a long way in showing the repository owner that you're a serious contributor.

Have an open issue linked in (optional)

An important tool of modern software development discipline is having an open issue (or bug, or ticket, or however else it's called in other systems) to discuss some problem or some missing feature we want to address.

An issue is more general than a PR description. An issue describes a problem; a PR describes a solution to that problem. Some issues require multiple PRs to be solved, and interlinking all these PRs through the issue is critical for later attempts at archaeology.

If in doubt - open an issue. Add all the context there. The PR will then reference the issue with a #<issue number> tag - this is something GitHub understands and will add a link between the two. A PR can also say Fixes #<issue number> if merging this PR means the issue is fully solved.

One of the most frustrating experiences for a repository maintainer is getting a PR without sufficient context of what it attempts to solve and why. Having an open issue with all the details is the best way to establish this context; the next sections address some additional ways.

I marked this section as (optional) because an issue isn't necessary in some cases. For example, typos in comments typically don't require an issue and a PR carries sufficient context. Minor changes in documentation also don't require issues in most cases.

If in doubt, create an issue. Linking this to the previous section - if an issue describing the problem already exists, make sure to link your PR to it - maintainers love PRs that solve open issues.

Write a useful PR title

This advice will read a bit like "what makes a good git commit message".

The PR title is extremely important. It's what people see when listing all open PRs. It's also commonly translated to be the first line of the merged commit, and shows up prominently in git log, etc. Take special care in crafting the PR title to be descriptive and useful, but not too long.

Some large repositories have special guidelines for writing PRs. For example, the PR title would start with the component name - "storage/remote: increase widget timeout". Look around - how do other PRs (that were successfully merged) look? Is there any contribution guide in the repository that details these conventions?

Write a detailed PR description

This ties strongly to the "Have an open issue linked in" advice. If the PR requires a long background description, it's better to do this in an issue and have a link in the PR. If there is no issue for some reason, the burden is on the PR description to explain the motivation for the change, and the approach taken in it.

But PRs and issues are also for diferent purposes. Sometimes, a PR description will have information that doesn't belong in an issue, such as details of the specific approach taken in the PR, benchmark numbers for this PR, etc.

The PR description will make it into the git commit log - add as much detail as you can. The repository mainainer can later tweak the commit log so they will remove things they don't need; if in doubt, add more details.

Adhere to the project's coding standards

Does the project have a contributors guide? Spend a couple of minutes looking for it.

Look at other PRs that were merged - what did their authors do?

Look at some of the existing code in the repository - try to match the style of your PR to the prevailing style in the existing code. Doing this shows the maintainer that you're a serious contributor who cares about the long term health of the project.

Be attentive to the smallest details: how much whitespace does the code have, including in comments? Is there a specific writing style - Oxford commas, one or two spaces after a period, and so on?

Add tests

If you're adding new code - make sure it's tested. Either add new tests, or point out in the PR description which existing tests cover it. If a test is too hard to add for some reason, explain why.

For changing existing code the situation is a bit more nuanced. Is the change addressing a current test failure? Which one? Which tests are affected by the change? Should new tests be added?

Spend a few minutes thinking about this and documenting your conclusions in the PR description. Again, this shows the maintainer that you're a serious contributor and your PR is more likely to get attention.

Make sure all tests pass

Many GitHub repositories have integration with CI tools, whereupon each PR gets automatically tested and the CI system adds notes to the PR about its passing or failing.

After sending a PR, watch out for this and address any failures. Maintainers are unlikely to pay attention to PRs that break the build or tests.

If the repository has no such tool, make sure to run all the tests you find in the project and ensure that your change doesn't affect them negatively. If some test breaks because it's bad, make sure to fix it. If some tests fail with or without your change, make sure to call this out in the PR description.

Be patient and friendly during code review

Once the PR is finally out, the contributor's task isn't done yet. In fact, most of the work may yet be ahead. The code review process is an important tenet of modern software development, and knowing how to behave is critical for success.

Whole book chapters have been written on code reviews, so I'll keep it short and simple here, focusing on open-source contributions. When sending a PR for a work project, it's obvious we should be extra friendly and kind with colleagues, right? Right?

But what about open source? You found an issue in some OSS project you use, and are sending a PR. Good for you! Do you expect the maintainer will be delighted about the contribution? Well, not necessarily, and it really depends on your demeanor.

OSS maintainers are notoriously overworked and underpaid. Sometimes they just want stability - as few changes as possible. Clearly if you report a critical bug they will likely be happy to fix it; but 99% of PRs are not for critical bugs - they are for minor bugs and new features. Here the PR presents a dilemma for the maintainer - someone is sending code, and this someone is very likely going to completely disappear after the PR lands, so the responsibility for the code moves to the maintainer. It's not surprising that in many cases, maintainers are cautions and even suspicious of every change.

When answering review comments be patient and friendly. Assume good intentions - the maintainer is taking extra burden to maintain additional code (especially with feature PRs) and it's their right to scrutinize it and take their time. Multiple rounds of reviews may be required. Be sure to be responsive and attentive to detail - acknowledge all comments, either by doing what the reviewer suggests, or (kindly) explaining your point of view. Add more tests if they ask you to (and you can't point to existing tests covering the same thing), add more comments if they ask you to.

GitHub webhook payload as a cloud function

2019-03-05T06:20:00-08:00

Back in 2014, I wrote a post describing a simple payload server for GitHub webhooks, using Python 3. That server could be deployed to any VPS listening on a custom port.

Now it's 2019, and deploying servers to VPSs doesn't make me feel hip enough. All the cool kids are into serverless now, so I decided to rewrite the same payload server in Go and deploy it as a Google Cloud Function. This brief post can serve as a basic tutorial on how to do it.

I assume you already have a GCP account (there's a free tier), and the gcloud command-line tool is configured to authenticate with your account and project name.

You can see the full code here, but this is the important part:

func Payload(w http.ResponseWriter, r *http.Request) {
  body, err := ioutil.ReadAll(r.Body)
  if err != nil {
    log.Println(err)
    return
  }
  log.Println("Header:\n---------")
  fmt.Println(r.Header)

  if !validateSignature(body, r) {
    m := "Signature validation failed"
    log.Println(m)
    w.Write([]byte(m))
    return
  }

  fmt.Println("Body:\n---------")
  log.Println(string(body))
}

Payload is a standard http.HandlerFunc, and its signature should be familiar to anyone who has written HTTP servers in Go. GitHub sends its payload as a POST request (hence our reading from r.Body) with some special headers for validation. The validation code runs a SHA1 HMAC to ensure that GitHub knows a secret key shared with the application (this helps keep intruders away from your payload server).

The full code sample has this validation code, as well as a simple unit test for Payload. It doesn't actually attempt to create a properly signed message, but checks that Payload is alive and returns a valid HTTP response. In general, it is highly recommended to unit-test these handlers locally, because cloud function deployment takes many seconds and isn't very convenient for short edit-test cycles.

To deploy this function, we'll go to the directory where payloadserver.go lives, and run:

$ gcloud functions deploy payloadserver \
      --entry-point Payload \
      --runtime go111 \
      --trigger-http \
      --set-env-vars HOOK_SECRET_KEY=<your secret key>

This prints out a URL for your function; it looks something like:

httpsTrigger:
  url: https://<region>-<project-name>.cloudfunctions.net/payloadserver

Which is what you'll point the GitHub webhook to. Configure the webhook to send all events, and then test it by creating or modifying some issue in your repository. The webhook management page on GitHub should now show the event in "Recent deliveries". You can also check the logs of your cloud function, either from the GCP control panel, or from the command-line:

$ gcloud functions logs read payloadserver

If everything ran successfully, you'll see the headers and the body of the payload emitted to the log. That's it!

Jokes about hipness aside, once you get the hang of it cloud functions seem like a particularly easy way to deploy simple web servers and apps for specific needs. There's a lot of powerful functionality behind the simple facade - for example, resources will automatically scale with the load. That said, be aware of the costs if you're doing it for anything high-volume.

Payload server in Python 3 for Github webhooks

2014-07-09T05:50:49-07:00

The Github Webhooks API is powerful and flexible, making it simple to integrate services with your source repository. Lately I've been tinkering with it a bit, but all the examples Github has are in Ruby. So I put together a simple demo server in Python 3. Though simple (it's completely self contained and only needs Python 3 to run), it's complete, covering even webhook security by verifying the signature created with the API's secret token.

Here it is:

import argparse
import hashlib
import hmac
from http.server import HTTPServer, BaseHTTPRequestHandler
import json
import pprint
import os
import sys

# It's not recommended to store the key within the code. Following
# http://12factor.net/config, we'll store this in the environment.
# Note that the key must be a bytes object.
HOOK_SECRET_KEY = os.environb[b'HOOK_SECRET_KEY']


class GithubHookHandler(BaseHTTPRequestHandler):
    """Base class for webhook handlers.

    Subclass it and implement 'handle_payload'.
    """
    def _validate_signature(self, data):
        sha_name, signature = self.headers['X-Hub-Signature'].split('=')
        if sha_name != 'sha1':
            return False

        # HMAC requires its key to be bytes, but data is strings.
        mac = hmac.new(HOOK_SECRET_KEY, msg=data, digestmod=hashlib.sha1)
        return hmac.compare_digest(mac.hexdigest(), signature)

    def do_POST(self):
        data_length = int(self.headers['Content-Length'])
        post_data = self.rfile.read(data_length)

        if not self._validate_signature(post_data):
            self.send_response(401)
            return

        payload = json.loads(post_data.decode('utf-8'))
        self.handle_payload(payload)
        self.send_response(200)


class MyHandler(GithubHookHandler):
    def handle_payload(self, json_payload):
        """Simple handler that pretty-prints the payload."""
        print('JSON payload')
        pprint.pprint(json_payload)


if __name__ == '__main__':
    argparser = argparse.ArgumentParser(description='Github hook handler')
    argparser.add_argument('port', type=int, help='TCP port to listen on')
    args = argparser.parse_args()

    server = HTTPServer(('', args.port), MyHandler)
    server.serve_forever()

Just run it at some port on your server and point the webhook you create to it. Currently it just runs on the server's root path (e.g. http://myserver.com:1234), but should be trivial to modify to any path.

By the way, I found ngrok to be invaluable for testing this. It creates a tunnel from your localhost's port to a unique URL you can set as the webhook destination on Github. This makes it possible to quickly iterate and test the server on your local machine.

Moving to Github - one year recap

2014-06-08T08:50:47-07:00

It's been a year since I switched all my personal projects from Bitbucket / Mercurial to Github / Git, so I think the time is right for a brief recap.

As I mentioned back then, the platform (Github vs. Bitbucket) served a larger role in the decision to switch than the source control system (Git vs. Mercurial). Bitbucket lets you use Git now if you want, so the latter difference is actually moot. It's the platform that remains the difference, and if I felt that Github has "won" the platform war a year ago, I feel even more so now. Even so far as being called the new résumé for developers, Github has definitely captured a very prominent place in the jargon and habits of our craft.

Amazingly, Bitbucket still hasn't caught up in terms of front-page information. On Github it's fairly easy, in a quick glance, to assess how active a developer is, which projects he contributes to, etc. On Bitbucket, all you see is a dull list of project names, not sorted in any useful way. Organizations, another cool Github concept, is also nowhere to be seen. Perhaps Bitbucket gave up on this fight, though, focusing on corporate users.

My main qualm with Bitbucket was that due to its lack of popularity I didn't get as much contribution to my projects as I hoped for. Had this improved? Certainly! Instead of "why don't you use Github" complaints, I now routinely get pull requests (or at least opened issues) for my projects. Several of my projects are starred by dozens of developers, and the most popular one - pycparser - now has over 40 forks!

Github pull requests are indeed a thing of beauty. Not that there's anything technically complex about them. It's a cultural thing. If you find a problem in a project, just send in a pull request. Most chances are it will be accepted. Pull requests have become a ubiquitous contribution currency, because of one very subtle, yet powerful factor. Github pull requests are part of your online identity. Once your pull request is merged into a project, it's forever retained in the log that you have contributed to that project. You being the direct link to your Github account / profile. For example, I commited a small fix to Django a few months ago - here it is, forever recorded and linked to my Github profile. The power of Github as the de-facto social network of developers cannot be ignored. It is way, way more significant than Linkedin.

Let's put it this way - actual commits beat empty endorsements, any day.

Github indeed serves the résumé role well, at least for me. I routinely receive job / interview offers or recruiter pitches based on my "impressive Github profile".

Even projects that are not formally hosted on Github take care to maintain a mirror there, because Github is such a familiar low-entry way to examine their code and even fork it. It's not uncommon for people to develop their changes in branches vs. the Github mirror, and sending patches to the real source repository when done. I know this happens in the LLVM & Clang world a lot. Maintaining Github mirrors of projects is quite easy - for example, it took me just a few hours to set up this semi-official Github mirror for CPython, and as for maintaining it... well, there's cron for that.

Github's popularity is also the cause of it being the first target of other projects that aim to make the life of developers easier. Travis CI is a blessing, and I use its Github integration extensively. All developers know how painful it is to set up and maintain continuous integration builds for their project. Travis & Github make this ridiculously easy, at least for the limited set of platforms Travis currently supports. Automatically run tests for each proposed pull request and tell me if it breaks anything? Shut up and take my money! Oh, it's free for open-source projects...