[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline

[GitBox <gi...@apache.org>]

gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946234388


##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,181 @@
+- Feature Name: Commit Message Guideline
+- Start Date: 2022-08-12
+- RFC PR: [apache/tvm-rfcs#0000](https://github.com/apache/tvm-rfcs/pull/88)
+- GitHub Issue: [apache/tvm#0000](https://github.com/apache/tvm/issues/0000)
+
+# Summary
+[summary]: #summary
+
+This RFC proposes adding a Commmit Message Guideline to TVM documentation to
+help guide contributors on how to write good commit messages when submitting
+code / PRs (Pull Requests) to Apache TVM.
+
+# Motivation
+[motivation]: #motivation
+
+Currently TVM commit logs are less than ideal because many commit messages lack
+valuable information and don't follow any format standard.
+
+Valuable information is usually left behind in Github PR conversations or
+discussion threads in the Discuss forum, making it hard to retrieve them when
+inspecting the commit messages -- using `git log`, for instance.
+
+Because commit messages are an indirect but important aspect of code quality,
+and also important for code maintenance, it is essential for a long term open
+source project to ensure that they meet high standards.
+
+The importance of commit messages conveying enough context and information about
+the code being changed will grow as the project grows and bad (poorly written)
+commit messages can affect negatively the code quality of future changes that
+would otherwise benefit from past good commit messages if they existed.
+
+Beyond code itself, poorly written commit messages can also affect the community
+in other ways. For example, by not providing to new contributors a consistent
+and complete history or context for the code changes, it can work as a barrier
+for new contributions because much more time will be necessary trying to
+understand what motivated a past critical but unclear change.
+
+Hence this Commit Message Guideline can help contributors to write good commit
+messages and so improve the current situation regarding the TVM commit logs.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+Commit Message Guideline
+
+Apache TVM uses the Github (GH) platform for patch submission and code review
+via Pull Requests (PRs). The final commit (title and body) that is merged into
+the Apache TVM main tree is composed of the PR's title and body and must be kept
+updated and reflecting the new changes in the code as per the reviews and
+discussions.
+
+Although these guidelines apply essentially to the PRs’ title and body messages,
+because GH auto-generates the PR’s title and body from the commits on a given
+branch, it’s recommended to follow these guidelines right from the beginning,
+when preparing commits in general to be submitted to the Apache TVM project.
+This will ease the creation of a new PR, avoiding rework, and also will help the
+review.
+
+The rules below will help to achieve uniformity that has several benefits, both
+for review and for the code base maintenance as a whole, helping you to write
+commit messages with a good quality suitable for the Apache TVM project,
+allowing fast log searches, bisecting, and so on.
+
+_PR/commit title_:
+
+* Guarantee a title exists (enforced);
+* Don’t use Github usernames in the title, like @username (enforced);
+* Check if a tag should be present as a hint about what component(s) of the code
+  the commits “touch”. For example [BugFix], [CI], [microTVM], and [TVMC]. Tags
+  go between square brackets and appear first in the title. Tags help reviewers
+  to identify the PRs they can/want to review and also help the release folks
+  when generating the release notes (enforced);
+* Use an imperative mood. Avoid titles like “Added operator X” and “Updated
+  image Y in the CI”, instead use the forms “Add feature X” and “Update image Y
+  in the CI” instead;
+* Observe proper use of caps at the beginning (uppercase for the first letter)
+  and for acronyms, like, for instance, TVM, FVP, OpenCL. Hence instead of
+  “fix tvm use of opencl library”, write it as “Fix TVM use of OpenCL library”;
+* No period at the end of the title is necessary.

Review Comment:
   I'm ok with the suggestion.
   
   I just would like to clarify that this rule is not enforced, in the sense it's essentially a recommendation and won't be a blocker for the PR -- no linter will regard it, for example. In v1 we discussed that for this case it could incur an unnecessary review "overhead" by requesting to an author to change such a thing for reviewers and authors on different timezones, for instance.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org