Github Branch Protection, TravisCI and Flake8

DM recommends using Github branch protection, TravisCI and Flake8 on repositories.

Github Branch Protection

All DM repositories should protect the master branch. Protected branches block some features of Git. Specifically DM protected branches can’t be edited from the web, force pushed, deleted or merged until their status checks pass. Furthermore status checks must pass using the latest base branch code.

Travis CI

TravisCI is a service that provides continuous integration for Github repositories. This service must be enabled for the repository before it will work. After it is enabled there will be a page available with the TravisCI status for the repository. For example lsst.utils https://travis-ci.org/lsst/utils.

Flake8

Flake8 is a command-line utility for enforcing style consistency across Python projects. It includes PyFlakes and PEP-0008 lint checks by default. DM uses the repository’s setup.cfg file to configure flake8. The python style guide has further details on specific lint check exceptions. The following setup.cfg file implements DM’s lint check exceptions:

sqre-gtf

sqre-gtf provides command line interfaces to use Github branch protection, TravisCI and Flake8. sqre-gtf runs on Python 2.7, 3.5 and 3.6. You can install it with

pip install sqre-gtf

If you haven’t used sqre-codekit or sqre-gtf before you will need to create a Github personal access token and put it in ~/.sq_github_token. The github-auth script can do this on your behalf.

github-auth -u <your_github_login>

        Type in your password to get an auth token from github
        It will be stored in ~/.sq_github_token
        and used in subsequent occasions.

Password for <your_github_login>: <your_github_password>
Enter 2FA code: <your_github_2FA>
Token written to ~/.sq_github_token

There are three core features that sqre-gtf provides. Configuration of Github branch protection, enabling the TravisCI webhook and configuring your repository to use TravisCI to run Flake8 validation.

An example of using sqre-gtf on lsst.utils follows

github-protect --owner lsst --repo utils --branch_name master # Add Github branch protection.
github-travis --owner lsst --repo utils # Enable the TravisCI webhook
github-update --owner lsst --repo utils --task stack --branch_name tickets/DM-NNNNN --commit_message "DM-NNNNN: Add .travis.yml and setup.cfg to run flake8." --pull --pull_message "DM-NNNNN: Add .travis.yml and setup.cfg to run flake8." # Create a commit and pull request adding .travis.yml and setup.cfg.

Now Github branch protection is enabled and TravisCI is enabled for the repository. The last command creates a PR with a single commit similar to lsst/utils #33. From there, if the repository does not meet the requirements of RFC-162 it will fail TravisCI. Additional changes may be required to pass TravisCI. @timj made such changes on lsst/utils #33.

Things to be Aware of Before Making Changes

When updating a repository it is time sensitive. As soon as TravisCI is enabled for your repository it will attempt to run a default TravisCI script on your repository which will likely fail until the sqre-gtf PR is merged. Another notable change is enabling Github’s branch protection. Users will be unable merge PRs until they pass TravisCI. This can always be disabled in the repository’s settings by an Overlord.