Infrastructure/Git/Hooks

KDE's Code Repositories are augmented by a number of special purpose scripts known as hooks, which carry out checks and perform actions on behalf of the developer. Certain hooks must be successful in order for a push or commit to be accepted.

Authorship metadata

This hook validates the name and email address for the author and committer of every Git commit. This is necessary to allow for the author of the commit to be reached by contributors later in time. A name is considered valid if it is a full name – it should not be a username or the first name of the person. Email addresses are considered invalid if the domain is not allowed, does not exist or cannot receive email.

Line endings

Text files which are committed to KDE repositories are required to be formatted using UNIX line endings ("\n"), rather than Windows ("\r\n") or very old Mac ("\r") format line endings. See https://en.wikipedia.org/wiki/Newline#Representation for details. This is necessary to prevent large changes in the content of files when contributors from different operating systems work on the same code. Because of the nature of this hook, it has been disabled for certain repositories which are specific to work on particular operating systems.

Filename restrictions

This hook prevents files which match certain regular expressions from being added to KDE code repositories. This usually blocks files which are generated, backups, build specific or binaries generated as part of a build. This is primarily to prevent accidental commits containing these files, which may clutter the repositories themselves.

Backup

This hook detects when destructive operations (such as deletions or force pushes) are being performed on a Git repository and creates a backup of each branch or tag which is affected. These backups are located at refs/backups/ in the repositories, and cannot be altered once created. If you need a backup removed, please file a ticket including an explanation of why this is necessary.

License checks

This is performed on newly added files to a repository, and checks them to ensure they comply with KDE Licensing Policy. It can recognise the GPL, LGPL, QPL, X11, MIT, BSD, MPL and Artistic licenses, as well as a public domain statement. Files which do not comply with the licensing policy cannot be distributed by the KDE project.

If a license is not recognised, contains an old address of the license publisher or if the file is automatically generated then a licensing problem will be flagged. In this event, the author of the commit will be sent a copy of the commit email.

Keywords

Certain keywords, when included in commit messages, will trigger the hooks to carry out other operations specific to that commit.

Each keyword must be on a separate line of the commit message with nothing else present on that line.

Keywords in use today:

• BUG:, ENHANCEMENT:, and FEATURE: [<ID of Bugzilla ticket> or <one-line description>]
  Denotes that this commit fixes a bug, improves something existing, or implements a new feature. If given the number of a Bugzilla ticket, it will be closed and the commit message's title will be added to any auto-generated release notes that parse git commits with these keywords. If given a one-line description, that text will be added to any auto-generated release notes that parse git commits with these keywords.
• FIXED-IN: <version>
  If the BUG:, ENHANCEMENT:, or FEATURE: keyword has been used to close a bug, this keyword will update the Bugzilla ticket's Version fixed in field. You can only select one version, so prefer the lowest release version that will actually have the fix.
• CHANGELOG: <optional one-line description>
  Denotes a miscellaneous user-visible change that should be mentioned in any auto-generated release notes that parse git commits with this keyword. Only use this if not using the BUG:, ENHANCEMENT:, or FEATURE: keywords.
• CCBUG: <ID of Bugzilla ticket>
  Posts the commit title and description as a comment to a Bugzilla ticket with the given ID number. Equivalent to emailing <bugnumber>@bugs.kde.org.
• CCMAIL: <email address>
  Posts the commit title and description as an email to the given e-mail address.
• GIT_SILENT
  Marks the commit message "silent" by adding "(silent)" to the subject line of the email, to allow filtering out trivial commits. Use these tags tag carefully and only for really uninteresting, uncontroversial commits.

These keywords were used historically, but are not used anymore:

• Differential Revision: https://phabricator.kde.org/D<number>
  Links the commit to the Differential on Phabricator and closes it. It *must* be the last line of the commit message. Unused since KDE migrated from Phabricator to GitLab.
• GUI: <optional one-line description>
  Indicates a user visible change in the user interface. Was used in the past to make the documentation team aware of such changes, but there's no longer a formal documentation team looking at these keywords.
• NO_CHANGELOG
  To avoid the commit being mentioned in changelogs. No longer used now that changelogs are not auto-generated — and if they were, they would consist of an allow-list of items denoted by the BUG:, ENHANCEMENT:, FEATURE:, or CHANGELOG: keywords.
• SVN_SILENT
  Same as GIT_SILENT; unnecessary because we use Git now.
• SVN_MERGE
  Special keyword for people that use the svnmerge script. Marks the commit message as being a merge commit by adding "(merge)" to the subject of the email. This way receivers can filter out emails that are caused by merging the same patch from one branch to another branch. Reviews of those emails is usually not needed. This keyword filters out the endless property changes used by this script. Unnecessary because we use Git now.