From 779564d9513d6970ca4927028b20cbaadbfa115f Mon Sep 17 00:00:00 2001 From: Jim Huang Date: Fri, 21 Feb 2025 18:37:40 +0800 Subject: [PATCH 1/3] Alert oversimplified commit messages for queue For functions with names starting with "q_" (e.g., "Implement q_size" or "Finish q_new"), require that the commit message include more detail in the body. Change-Id: I7f3d6f1f13d2f56ae69e858617805baf4c25a1e8 --- scripts/commit-msg.hook | 50 ++++++++++++++++++++++++----------------- 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/scripts/commit-msg.hook b/scripts/commit-msg.hook index 17629cc1a..127262033 100755 --- a/scripts/commit-msg.hook +++ b/scripts/commit-msg.hook @@ -249,36 +249,46 @@ validate_commit_message() { # 6. Wrap the body at 72 characters # ------------------------------------------------------------------------------ -URL_REGEX='^[[:blank:]]*(https?|ftp|file)://[-A-Za-z0-9+&@#/%?=~_|!:,.;]*[-A-Za-z0-9+&@#/%=~_|]' - -# Ensure the commit message lines are loaded into an array. -readarray -t COMMIT_MSG_LINES < "$COMMIT_MSG_FILE" - -for i in "${!COMMIT_MSG_LINES[@]}"; do - LINE="${COMMIT_MSG_LINES[$i]}" - # Trim leading and trailing whitespace. - TRIMMED_LINE="${LINE#"${LINE%%[![:space:]]*}"}" - TRIMMED_LINE="${TRIMMED_LINE%"${TRIMMED_LINE##*[![:space:]]}"}" - LINE_NUMBER=$((i+1)) - if [ "${#TRIMMED_LINE}" -gt 72 ] && ! [[ "$TRIMMED_LINE" =~ $URL_REGEX ]]; then - add_warning "$LINE_NUMBER" "Wrap the body at 72 characters (${#TRIMMED_LINE} chars)" - fi -done - - # 7. Use the body to explain what and why vs. how - # ------------------------------------------------------------------------------ + URL_REGEX='^[[:blank:]]*(https?|ftp|file)://[-A-Za-z0-9+&@#/%?=~_|!:,.;]*[-A-Za-z0-9+&@#/%=~_|]' + + # Ensure the commit message lines are loaded into an array. + readarray -t COMMIT_MSG_LINES < "$COMMIT_MSG_FILE" + + for i in "${!COMMIT_MSG_LINES[@]}"; do + LINE="${COMMIT_MSG_LINES[$i]}" + # Trim leading and trailing whitespace. + TRIMMED_LINE="${LINE#"${LINE%%[![:space:]]*}"}" + TRIMMED_LINE="${TRIMMED_LINE%"${TRIMMED_LINE##*[![:space:]]}"}" + LINE_NUMBER=$((i+1)) + if [ "${#TRIMMED_LINE}" -gt 72 ] && ! [[ "$TRIMMED_LINE" =~ $URL_REGEX ]]; then + add_warning "$LINE_NUMBER" "Wrap the body at 72 characters (${#TRIMMED_LINE} chars)" + fi + done - # 8. Do no write single worded commits + # 7. Do no write single worded commits # ------------------------------------------------------------------------------ COMMIT_SUBJECT_WORDS=(${COMMIT_SUBJECT_TO_PROCESS}) test "${#COMMIT_SUBJECT_WORDS[@]}" -gt 1 test $? -eq 0 || add_warning 1 "Do no write single worded commits" - # 8a. Do not mention C source filenames + # 7a. Do not mention C source filenames [[ ${COMMIT_SUBJECT_TO_PROCESS} =~ [_a-zA-Z0-9]+\.[ch]$ ]] test $? -eq 1 || add_warning 1 "Avoid mentioning C source filenames" + # 8. Use the body to explain what and why vs. how + # ------------------------------------------------------------------------------ + + # Count non-comment, non-blank lines excluding "Change-Id:". + NON_COMMENT_COUNT=$(sed '/^[[:space:]]*#/d;/^[[:space:]]*$/d;/^[[:space:]]*Change-Id:/d' "$COMMIT_MSG_FILE" | wc -l | xargs) + + # If the subject is oversimplified for a queue function OR queue.c is modified, + # and there is only one meaningful line, issue a warning. + if { [[ "$COMMIT_SUBJECT_TO_PROCESS" =~ ^(Implement|Finish)[[:space:]]+q_[[:alnum:]_]+\(?\)?$ ]] || \ + git diff --cached --name-only | grep -Eq '(^|/)queue\.c$'; } && [ "$NON_COMMENT_COUNT" -le 1 ]; then + add_warning 1 "Commit message oversimplified. Use the commit message body to explain what and why." + fi + # 9. Do not start the subject line with whitespace # ------------------------------------------------------------------------------ From 0227ced9c778ad4c4f86708679cb0ece09f8bad6 Mon Sep 17 00:00:00 2001 From: Jim Huang Date: Fri, 21 Feb 2025 20:59:33 +0800 Subject: [PATCH 2/3] Avoid using backtick characters in commit subject MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Backticks are disallowed in commit messages because they can be easily confused with single quotes on some terminals, reducing readability. Moreover, using backticks to highlight symbols or function names is unnecessary—plain text or simple single quotes provide sufficient clarity and emphasis. Change-Id: I6a1a78546f21fe3a227922ba10ff4d8837066648 --- scripts/commit-msg.hook | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/scripts/commit-msg.hook b/scripts/commit-msg.hook index 127262033..bcb64e529 100755 --- a/scripts/commit-msg.hook +++ b/scripts/commit-msg.hook @@ -265,16 +265,17 @@ validate_commit_message() { fi done - # 7. Do no write single worded commits + # 7. Ensure the commit subject has more than one word. # ------------------------------------------------------------------------------ - COMMIT_SUBJECT_WORDS=(${COMMIT_SUBJECT_TO_PROCESS}) - test "${#COMMIT_SUBJECT_WORDS[@]}" -gt 1 - test $? -eq 0 || add_warning 1 "Do no write single worded commits" + if [ "$(echo "$COMMIT_SUBJECT_TO_PROCESS" | wc -w)" -le 1 ]; then + add_warning 1 "Do not write single-word commits. Provide a descriptive subject" + fi - # 7a. Do not mention C source filenames - [[ ${COMMIT_SUBJECT_TO_PROCESS} =~ [_a-zA-Z0-9]+\.[ch]$ ]] - test $? -eq 1 || add_warning 1 "Avoid mentioning C source filenames" + # 7a. Avoid using C source filenames as the commit subject. + if [[ "$COMMIT_SUBJECT_TO_PROCESS" =~ ^[_a-zA-Z0-9]+\.[ch]$ ]]; then + add_warning 1 "Avoid mentioning C source filenames in the commit subject" + fi # 8. Use the body to explain what and why vs. how # ------------------------------------------------------------------------------ @@ -295,12 +296,12 @@ validate_commit_message() { [[ ${COMMIT_SUBJECT_TO_PROCESS} =~ ^[[:blank:]]+ ]] test $? -eq 1 || add_warning 1 "Do not start the subject line with whitespace" - # 10. Avoid single word commit messages in subject + # 10. Disallow backticks anywhere in the commit message. # ------------------------------------------------------------------------------ - word_count=$(echo "$COMMIT_SUBJECT_TO_PROCESS" | wc -w) - test "$word_count" -gt 1 - test $? -eq 0 || add_warning 1 "Commit subject should contain more than one word. Summarize your changes" + if sed '/^[[:space:]]*#/d;/^[[:space:]]*$/d' "$COMMIT_MSG_FILE" | grep -q "\`"; then + add_warning 1 "Avoid using backticks in commit messages" + fi # 11. Avoid commit subject that simply states a file update (e.g. "Update console.c") # ------------------------------------------------------------------------------ From 00e6069b34fec4437091daab4fb08248cd3b3436 Mon Sep 17 00:00:00 2001 From: Jim Huang Date: Fri, 21 Feb 2025 22:38:50 +0800 Subject: [PATCH 3/3] Avoid using parentheses in commit subjects Excessive use of parentheses '()' can clutter the subject line, making it harder to quickly grasp the essential message. Change-Id: Icde5cc319200a5269232a9dcf5efa3e774a624d3 --- scripts/commit-msg.hook | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/scripts/commit-msg.hook b/scripts/commit-msg.hook index bcb64e529..55f5ed36e 100755 --- a/scripts/commit-msg.hook +++ b/scripts/commit-msg.hook @@ -268,25 +268,30 @@ validate_commit_message() { # 7. Ensure the commit subject has more than one word. # ------------------------------------------------------------------------------ - if [ "$(echo "$COMMIT_SUBJECT_TO_PROCESS" | wc -w)" -le 1 ]; then + if [ "$(echo "${COMMIT_SUBJECT_TO_PROCESS}" | wc -w)" -le 1 ]; then add_warning 1 "Do not write single-word commits. Provide a descriptive subject" fi # 7a. Avoid using C source filenames as the commit subject. - if [[ "$COMMIT_SUBJECT_TO_PROCESS" =~ ^[_a-zA-Z0-9]+\.[ch]$ ]]; then + if [[ "${COMMIT_SUBJECT_TO_PROCESS}" =~ ^[_a-zA-Z0-9]+\.[ch]$ ]]; then add_warning 1 "Avoid mentioning C source filenames in the commit subject" fi + # 11a. Disallow parentheses in the commit subject. + if [[ ${COMMIT_SUBJECT_TO_PROCESS} =~ [\(\)] ]]; then + add_warning 1 "Avoid using parentheses '()' in commit subjects" + fi + # 8. Use the body to explain what and why vs. how # ------------------------------------------------------------------------------ # Count non-comment, non-blank lines excluding "Change-Id:". - NON_COMMENT_COUNT=$(sed '/^[[:space:]]*#/d;/^[[:space:]]*$/d;/^[[:space:]]*Change-Id:/d' "$COMMIT_MSG_FILE" | wc -l | xargs) + NON_COMMENT_COUNT=$(sed '/^[[:space:]]*#/d;/^[[:space:]]*$/d;/^[[:space:]]*Change-Id:/d' "${COMMIT_MSG_FILE}" | wc -l | xargs) # If the subject is oversimplified for a queue function OR queue.c is modified, # and there is only one meaningful line, issue a warning. - if { [[ "$COMMIT_SUBJECT_TO_PROCESS" =~ ^(Implement|Finish)[[:space:]]+q_[[:alnum:]_]+\(?\)?$ ]] || \ - git diff --cached --name-only | grep -Eq '(^|/)queue\.c$'; } && [ "$NON_COMMENT_COUNT" -le 1 ]; then + if { [[ "${COMMIT_SUBJECT_TO_PROCESS}" =~ ^(Implement|Finish|Complete)[[:space:]]+q_[[:alnum:]_]+\(?\)?$ ]] || \ + git diff --cached --name-only | grep -Eq '(^|/)queue\.c$'; } && [ "${NON_COMMENT_COUNT}" -le 1 ]; then add_warning 1 "Commit message oversimplified. Use the commit message body to explain what and why." fi @@ -299,14 +304,14 @@ validate_commit_message() { # 10. Disallow backticks anywhere in the commit message. # ------------------------------------------------------------------------------ - if sed '/^[[:space:]]*#/d;/^[[:space:]]*$/d' "$COMMIT_MSG_FILE" | grep -q "\`"; then + if sed '/^[[:space:]]*#/d;/^[[:space:]]*$/d' "${COMMIT_MSG_FILE}" | grep -q "\`"; then add_warning 1 "Avoid using backticks in commit messages" fi # 11. Avoid commit subject that simply states a file update (e.g. "Update console.c") # ------------------------------------------------------------------------------ - if [[ $COMMIT_SUBJECT_TO_PROCESS =~ ^Update[[:space:]]+([^[:space:]]+)$ ]]; then + if [[ ${COMMIT_SUBJECT_TO_PROCESS} =~ ^Update[[:space:]]+([^[:space:]]+)$ ]]; then candidate="${BASH_REMATCH[1]}" # Only warn if the candidate filename ends with .c or .h if [[ $candidate =~ \.(c|h)$ ]]; then