util/git-commit-msg.py

   1 #!/usr/bin/env python3
   2 #
   3 # Copyright (c) 2019 Inria
   4 # All rights reserved
   5 #
   6 # Redistribution and use in source and binary forms, with or without
   7 # modification, are permitted provided that the following conditions are
   8 # met: redistributions of source code must retain the above copyright
   9 # notice, this list of conditions and the following disclaimer;
  10 # redistributions in binary form must reproduce the above copyright
  11 # notice, this list of conditions and the following disclaimer in the
  12 # documentation and/or other materials provided with the distribution;
  13 # neither the name of the copyright holders nor the names of its
  14 # contributors may be used to endorse or promote products derived from
  15 # this software without specific prior written permission.
  16 #
  17 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28
  29 # If your commit has been canceled because of this file, do not panic: a
  30 # copy of it has been stored in ./.git/COMMIT_EDITMSG
  31
  32 import os
  33 import re
  34 import sys
  35 from maint.lib import maintainers
  36
  37 from style.repo import GitRepo
  38
  39 def _printErrorQuit(error_message):
  40     """
  41         Print an error message, followed my a help message and inform failure.
  42
  43         @param error_message A message describing the error that caused the
  44             failure.
  45     """
  46     print(error_message)
  47
  48     print("The commit has been cancelled, but a copy of it can be found in "
  49           + sys.argv[1] + " : ")
  50
  51     print("""
  52 --------------------------------------------------------------------------
  53     """)
  54     print(open(sys.argv[1], "r").read())
  55     print("""
  56 --------------------------------------------------------------------------
  57     """)
  58
  59     print("""
  60 The first line of a commit must contain one or more gem5 tags separated by
  61 commas (see MAINTAINERS.yaml for the possible tags), followed by a colon and
  62 a commit title. There must be no leading nor trailing whitespaces.
  63
  64 This header line must then be followed by an empty line. A detailed message,
  65 although highly recommended, is not mandatory and can follow that empty line.
  66
  67 e.g.:
  68     cpu: Refactor branch predictors
  69
  70     Refactor branch predictor code to improve its readability, moving functions
  71     X and Y to the base class...
  72
  73 e.g.:
  74     mem,mem-cache: Improve packet class readability
  75
  76     The packet class...
  77 """)
  78     sys.exit(1)
  79
  80 def _validateTags(commit_header):
  81     """
  82         Check if all tags in the commit header belong to the list of valid
  83         gem5 tags.
  84
  85         @param commit_header The first line of the commit message.
  86     """
  87
  88     # List of valid tags
  89     maintainer_dict = maintainers.Maintainers.from_file()
  90     valid_tags = [tag for tag, _ in maintainer_dict]
  91
  92     # Remove non-tag 'pmc' and add special tags not in MAINTAINERS.yaml
  93     valid_tags.remove('pmc')
  94     valid_tags.extend(['RFC', 'WIP'])
  95
  96     tags = ''.join(commit_header.split(':')[0].split()).split(',')
  97     if (any(tag not in valid_tags for tag in tags)):
  98         invalid_tag = next((tag for tag in tags if tag not in valid_tags))
  99         _printErrorQuit("Invalid Gem5 tag: " + invalid_tag)
 100
 101 # Go to git directory
 102 os.chdir(GitRepo().repo_base())
 103
 104 # Get the commit message
 105 commit_message = open(sys.argv[1]).read()
 106
 107 # The first line of a commit must contain at least one valid gem5 tag, and
 108 # a commit title
 109 commit_message_lines = commit_message.splitlines()
 110 commit_header = commit_message_lines[0]
 111 commit_header_match = \
 112     re.search("^(fixup! )?(\S[\w\-][,\s*[\w\-]+]*:.+\S$)", commit_header)
 113 if ((commit_header_match is None)):
 114     _printErrorQuit("Invalid commit header")
 115 if commit_header_match.group(1) == "fixup! ":
 116     sys.exit(0)
 117 _validateTags(commit_header_match.group(2))
 118
 119 # Make sure commit title does not exceed threshold. This line is limited to
 120 # a smaller number because version control systems may add a prefix, causing
 121 # line-wrapping for longer lines
 122 commit_title = commit_header.split(':')[1]
 123 max_header_size = 65
 124 if (len(commit_header) > max_header_size):
 125     _printErrorQuit("The commit header (tags + title) is too long (" + \
 126         str(len(commit_header)) + " > " + str(max_header_size) + ")")
 127
 128 # Then there must be at least one empty line between the commit header and
 129 # the commit description
 130 if (commit_message_lines[1] != ""):
 131     _printErrorQuit("Please add an empty line between the commit title and " \
 132         "its description")
 133
 134 # Encourage providing descriptions
 135 if (re.search("^(Signed-off-by|Change-Id|Reviewed-by):",
 136     commit_message_lines[2])):
 137     print("Warning: Commit does not have a description")
 138
 139 sys.exit(0)