Sysadmin/CommitHooks

KDE Commit Hooks

The commit hooks are a set of scripts which are executed on KDE's Git server when you push a set of commits to a repository. Which sections of the hooks are executed can depend upon the repository you are interacting with at the time.

Prior to acceptance

Prior to accepting any commit into the repository however, these hooks audit commits inbound to the KDE repository. Three types of audit are performed: End of line, filename and metadata.

The End of line audit verifies that all lines you have added to files in the commits you are pushing to the repository use Unix standard end of line characters. Any commit which uses Windows or Mac end of line characters will be rejected, with a message indicating which commit and file you need to fix.

The filename audit verifies that you have not changed a file or directory name which is not permitted in KDE repositories. These names are usually those which are created automatically as backups, by build systems or other automated systems. Any commit with a path matching a name not permitted in the repositories will be rejected by the commit hooks, with a message indicating which commit and name is not permitted.

The metadata audit ensures that the author and committer email addresses specified in the commits are valid. Invalid email addresses include those which fail to resolve to either a MX or A dns record. localhost is also included as an invalid address. Any commit with an invalid email address will be rejected by the commit hooks, with a message indicating which commit and email address was problematic.

In addition, checks on the type of change you are trying to perform will made. Changes to refs other than in the heads, tags and notes namespaces will be prevented by the commit hooks. In addition, creation of a ref with the name of "HEAD" will also be prevented.

Post acceptance

Once your commits have passed audit, the commit hooks may take several actions depending on the repository, and the action you are performing.

If you are performing a destructive action, such as a ref deletion or force push, then the commit hooks will automatically backup the ref as it currently stands to refs/backup/<ref type>-<ref name>-<timestamp> prior to accepting your change.

Some repositories may also have arranged special actions to take place, such as notes being added to kdepim commits to the enterprise/e3 branch.

After these actions, a helpful url to the last commit you are pushing up will be output. The hooks will then proceed to send notifications by email, and to CIA.vc of new commits.

Email notifications

All pushes to normal and website repositories will cause an email to be sent to [email protected]. These emails will include information about your commit to allow for post commit code review to take place.

The email notification will also do several further checks to your commits, and may include you in the Cc field of the email if problems are found. These problems include licensing, unsafe commands and trailing whitespace. It is recommended to fix these issues in the code you have pushed to KDE repositories. The list of files affected by the commit is included in the message, and will have markers beside those files it found issue with.

Licensing checks will only be done to files that are newly added to the repository. These checks look for many known free software licenses. If a license cannot be identified, or the address of certain licenses is out of date, then a problem will be detected. Information on what problem it found will be included in the marker.

Unsafe checks will be done to any line of code which has been changed in the commit. Unsafe command include those which invoke external commands or parse string. Information on what type of unsafe issue was detected is not included in the marker. Unsafe issues may cause portability issues between platforms or create vulnerabilities in the code.

Trailing whitespace issues are raised when changes to a *.desktop file are made, and include trailing spaces. Trailing spaces make *.desktop files invalid, and may cause issues in other applications which rely on their format.

CIA.vc notifications

Similar to email notifications, all pushes to normal and website repositories will cause an email to be sent to [email protected]. These notifications will include information needed by CIA to track the activity of the KDE Project, and may result in messages being posted to various channels on Freenode as a result.