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. These can alter bugs and review requests or inform others via email that a commit has been made. In order to have effect, each keyword must be on a separate line of the commit message with nothing else present on that line.
CCMAIL: <email address>
Sends a copy of the commit email to the specified email address. Multiple email addresses can be specified by separating the addresses with a comma, or by repeating the keyword for each email address.
BUG: <bug number>
Marks the bugs mentioned as fixed on KDE Bugzilla if the author of the commit has sufficient permission. A comment is also made including the commit message, and the commit link field of the bug will be set. Multiple bugs can be specified by separating them with any non-numeric character or by repeating the keyword for each bug.
CCBUG: <bug number>
Makes a comment on the bugs mentioned using information from the commit. Multiple bugs can be specified in the same manner as the BUG keyword.
FIXED-IN: <string>
Sets the “Fixed In” field of all bugs mentioned with the BUG keyword. Only the first occurrence of this keyword will have any effect, with subsequent entries having no effect.
REVIEW: <review id>
Marks the mentioned review requests on Reviewboard as submitted and adds a comment including information about the commit. Multiple review requests can be specified by separating them with any non-numeric character or by repeating the keyword for each review request.
Differential Revision: https://phabricator.kde.org/DXXXXwhere XXXX is the Differential number
Marks the mentioned review requests on Phabricator as submitted and adds a comment including information about the commit. Multiple review requests can be specified by separating them with any non-numeric character or by repeating the keyword for each review request.
GUI:
Used to indicate visible changes in the user interface. This will send a copy of the commit email to the KDE Documentation team, making them aware of the change.
SCM_SILENT
Adds (silent) to the subject of the commit emails sent out to allow contributors to filter out trivial commits. This should only be used for uninteresting and uncontroversial commits. It is also known as GIT_SILENT, SVN_SILENT or CVS_SILENT which have the same meaning and effect.