Brussels / 3 & 4 February 2018

schedule

Simplifying the contribution process for both contributors & maintainers

A case study of the GitHub integration in EasyBuild


Despite platforms like GitHub & co, several hurdles remain for wannabe contributors, on top of whatever skills were required to puzzle together the contribution, especially for people that are not software developers themselves. Examples include:

  • minimal experience with the VCS used by the project (Git, Mercurial, ...);
  • some familiarity with the platform where the project repository is located (GitHub, GitLab, Bitbucket, ...);
  • being aware of the project-specific contribution policy (for example feature & target branches, how to ;

Although these hurdles can be overcome with a reasonable amount of effort, for example by reading the project's documentation or following some basic tutorials, they turn out to be a showstopper for some people. Possible reasons include:

  • limited interest in getting familiar with all required details, especially for first-time or infrequent contributors;
  • a lack of time to learn how to overcome these hurdles;
  • becoming demotivated quickly because of problems encountered while following the contribution process;

This can result in a significant amount of (potentially very useful) lost contributions...

In addition, project maintainers often lack the time required to process all incoming contributions. Doing so not only requires a visual review of the code changes, but also testing, enforcing code style requirements, providing feedback, etc.

In this talk, I will outline the extensive GitHub integration that has been implemented in EasyBuild, a framework implemented in Python for building and installing (scientific) software on High Performance Computing (HPC) systems.

The EasyBuild command line interface has been extended to add support for:

  • previewing pull requests by comparing with current state of the project repository;
  • fully automatically creation of new pull requests (covering both the Git workflow & GitHub interface);
  • updating existing pull requests to resolve problems or implement suggestions made by maintainers;
  • testing contributions by pulling in the changes from GitHub for local testing;
  • uploading test reports back into pull requests to efficiently communicate whether the contribution works on other systems;
  • reviewing pull requests by cross-referencing with existing relevant files (if any);
  • merging pull requests after checking that all requirements are met (approval by Travis CI, successful test report, visual review by a maintainer, correct target branch, milestone set, ...)

In addition a bot was implemented to automatically notify contributors & maintainers that the Travis CI build for a pull request is failing (which is not supported by Travis CI itself).

These features have been implemented by leveraging the GitPython library, the GitHub REST API, and the Travis CI API.

They have proven invaluable for both contributors (regardless of experience) and EasyBuild maintainers, by streamlining the contribution process. In addition, this has resulted in:

  • significantly reduced effort to contribute (even for experienced contributors);
  • an increase in contributors & contributions;
  • better consistency in contributions;
  • less time spent by maintainers to process contributions.

I hope this talk can motivate other projects (large & small) to implement similar features to simplify their contribution process, since this is a critical part of building a community around a software project. The EasyBuil features that are outlined can also be implemented in other projects, regardless of the programming language being used and the scope of the project.

Speakers

Photo of Kenneth Hoste Kenneth Hoste

Links