cEP-0016.md

Git Commit Content Inspection

Metadata
cEP	16
Version	1.0
Title	Git Commit Content Inspection
Authors	Kriti Rohilla mailto:kritirohilla567@gmail.com
Status	Implementation due
Type	Process

Abstract

This document describes coala process rules which will be enforced by the GitCommitBear.

Introduction

GitCommitBear at present performs a check on the content of regular commits made in a repository that includes performing checks on the shortlog and body of commits. However, there are some cases that need to be taken care of separately.

One such case is that of "GitHub Pull Request temporary merge commits". These commits are automatically created by GitHub in refs/pull/(\d+)/merge git remote reference. The GitCommitBear does not identify them at present and fails causing the Travis CI build for corresponding PR to fail as well. Ideally the GitCommitBear should run on the parent of this merge commit.

Also, there are many special types of commit messages that should be used only in conjunction with patches containing a special type of content.

For example, git revert commit which is used to revert any previous commit and git merge commit which is generated whenever someone performs a GitHub rebase and tries to merge master onto the pull request. Rebase and merge on GitHub will always update the committer information and create new commit SHAs which is not correct. These commits generate a default commit message that is very concise and not according to coala’s standards. The coala project wants to allow git revert commits, but does not want to accept git merge commits as the repositories are strictly fast-forward merges that do not have an extra commit.

In cases where some tests are not required by any pull request made to coala, some special sequences can be added to git commit messages to instruct tools to operate in a certain way.

This project is about detecting such commits and verifying that they are correct according to the configuration settings in .coafile

Background

.coafile is a project-wide coala configuration file which is used to specify what is checked with which bears for a project.

The workaround that coala uses currently to handle the problem of GitHub Pull Request temporary merge commits in travis.yml is:

if [[ "$TRAVIS_PULL_REQUEST" != "false" ]]; then
  sed -e '/bears = GitCommitBear/d' .coafile > .coafile.new
  mv .coafile.new .coafile
fi

Below are some code snippets of .coafile from different projects depicting their use of GitCommitBear.

Projects- coala/coala, coala/projects, coala/documentation

[commits]
bears = GitCommitBear
shortlog_regex = ([^:]*|[^:]+: [A-Z0-9*].*)
shortlog_trailing_period = False

Projects- coala/coala-bears, coala/coala-quickstart, coala/corobo

[all.commit]
bears = GitCommitBear
shortlog_trailing_period = False
shortlog_regex = ([^:]*|[^:]+: [A-Z0-9*].*)
body_close_issue = True
body_close_issue_full_url = True
body_close_issue_on_last_line = True
body_enforce_issue_reference = False

Project- coala/coala-atom

[commit]
bears = GitCommitBear

Proposed Change

This project would allow organizations to customize the .coafile to allow following settings in the [commit] section.

[commit]
bears = GitCommitBear, CISkipInspectBear, GitMergeInspectBear, GitRevertInspectBear
allow_skip_ci_build = False
allow_git_merge_commit = False
allow_git_revert_commit = True

GitHub Pull Request temporary merge commits would be inspected by making changes in the GitCommitBear. For other special commits, a meta bear called VCSCommitBear would be used to provide information about the HEAD commit like commit message, commit SHA, type of commit and list of modified, added and delete files as HiddenResult which will be used be other bears for inspection of each special commit separately.

Here is the detailed implementation stepwise:

1. We start by identifying different types of special commits namely GitHub Pull Request temporary merge commits, git revert , git merge and commits that disable CI builds.
2. Each type of commit is then handled as a separate case.
3. For GitHub Pull Request temporary merge commits:
   • As a solution to this problem, settings will be added in GitCommitBear that would identify GitHub Pull Request temporary merge commits and ignore them.
   • GitCommitBear would identify and check contents of the unmerged parent of these merge commits.
4. A meta bear called VCSCommitBear would be created that would return a CommitResult comprising of a tuple that will contain information about the type of git commit, commit sha, list of parent commits and lists of modified files, added and deleted files. This meta bear would be used to inspect each type of special commit.
5. For commits that disable CI builds: This would involve making a new bear named CISkipInspectBear to inspect commits that disable CI builds. This bear would contain metadata about various CI providers that are supported by the project such as Circle CI, Travis CI, Semaphore CI etc. Most of the CI providers use sequences like [ci skip] and [skip ci] for skipping CI build on commits. CI build don't occur for commits that have either of these sequences anywhere in the commit message. This bear would inspect the changes made in such commits and verify that they can skip CI build that is with respect to modified files and whether the corresponding CI engine allows skipping build or not. An appropriate message is returned if skipping build is not supported.
   • The commit message of HEAD commit as returned by VCSCommitBear is checked to see if it tries to escape CI build. If yes, the HEAD commit is inspected further, otherwise return.
   • Files modified in the commit should include files that are not covered by .coafile or tests. If this is not the case, an error is raised to exclude [ci skip] or [skip ci] from the commit message.
6. For merge commits:
   • If the commit type from the output of VCSCommitBear indicates that the commit is a git merge commit, inspection is done in GitMergeInspectBear otherwise return.
   • GitMergeInspectBear will be used by finding if the commit tries to merge master or any other branch onto the pull request. A message is displayed to perform a git rebase instead in such case.
7. For revert commits:
   • The commit message of HEAD commit as returned by VCSCommitBear is checked to see if it is a git revert commit. If yes, the HEAD commit is inspected further, otherwise return.
   • In GitRevertInspectBear, the patches of both commits are compared to ensure that they are in fact reverse of each other. Minor differences are allowed.
   • In case of total mismatch, a note in the commit message highlighting that it is not a clean revert is expected.
   • A message suggesting improvements in the commit message is displayed.