You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tvm.apache.org by GitBox <gi...@apache.org> on 2022/08/15 15:55:24 UTC
[GitHub] [tvm-rfcs] gromero opened a new pull request, #88: [RFC] Add Commit Message Guideline
gromero opened a new pull request, #88:
URL: https://github.com/apache/tvm-rfcs/pull/88
This RFC proposes adding a Commmit Message Guideline to Apache TVM
documentation to help guide contributors on how to write good commit
messages when submitting code / Pull Requests.
Co-authored-by: Leandro Nunes <le...@arm.com>
--
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
[GitHub] [tvm-rfcs] mbaret commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
mbaret commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947301263
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
Review Comment:
I think given part of the committing process involves the committer copying the title/body of the PR, it's not unreasonable for them to also add a period at that stage and would add no time to the review. Obviously if this gets forgotten it's not the end of the world, but I think the guidance should be in favour of fixing minor issues rather than leaving it up to interpretation.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946242654
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
+changes having one commit for the fix and another one for the test, applying the
+rules and recommendations in this guideline to each commit.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. The only
+recommendation is that if the additional commits render the PR title and/or body
+outdated then the PR title and body must reflect the new changes in the code and
+be updated accordingly (remember that the PR title and body will be used to
+compose the final commit message that will land in the main tree).
Review Comment:
I agree with @mbaret I'll improve this part and post a v3.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r948483949
##########
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
Review Comment:
@leandron @tkonolige Tags are marked as "enforced", but I'm not totally convinced of it, but I don't strongly oppose to that too. If we want to keep this way I think just the presence of tags must be enforced, not the capitalization etc. Also, the bullet on tags starts with "Check if a tag should be present as a hint...", if it's indeed enforced that must be chanced, since it would not be optional. PTAL.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947337486
##########
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
Review Comment:
@tkonolige I'll added that to the CMG (Commit Message Guideline). But just to clarify, did you mean camel case (or even upper camel case) instead of snake case? I understand snake case would be for instance [bug_fix]...
--
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
[GitHub] [tvm-rfcs] tkonolige commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
tkonolige commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947345249
##########
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
Review Comment:
Whoops I meant upper camel case.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946267445
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
Review Comment:
@tqchen @mbaret I think I'm agree with both of you here, but clearly I failed to express it in the text :) Let me try to explain this paragraph better so you can tell me if that's indeed the case.
I think we are all agreeing that a fix should always come with a testcase.
I'm not saying here that the fix should be submitted in a PR and the testcase be submitted in another PR. I'm departing from the fact that we squash the commits of a PR anyways in the end (unfortunately, I have to say), so I'm just trying to say that for sake of reviewing it's recommended (or desirable) the PR (which has two commits: fix + testcase in the example) must have these two commits split in a reasonable way, with due commit messages, like not as single commit with fix code and testcase code intertwined all together -- as sometimes it happens. I'm trying here to just give some advice to actually ease the review process.
But OTOH I agree with @tqchen about the focus on the most important part, the message itself being descriptive. I'm ok on removing this paragraph. @leandron do you agree?
--
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
[GitHub] [tvm-rfcs] junrushao1994 commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
junrushao1994 commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949468894
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. However if the
+additional commits render the PR title and/or body outdated then it's the
+author's responsibility to keep the PR title and body in sync with new changes
+in the code and updated the PR title and body accordingly (remember that the PR
+title and body will be used to compose the final commit message that will land
+in the main tree).
+
+Committers will seek to fix any issues with the commit message prior to
+committing but they retain the right to inform the author of the rules and
+encourage them to follow them in future. Also, they retain the right to ask to
+the author to update the PR title and/or body when they are not correctly
+updated or fixed.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+TVM Community must reach a certain concensus about the rules in this guideline,
+hence this RFC will be voted.
+
+Once it's voted and approved the Commit Message Guideline text will be added to
+`./docs/contribute/pull_request.rst` doc, under section 'Submit a Pull Request',
+below subsection 'Guidelines', as a subsection named “Commit Message Guideline”.
+The text in the second-last item in subsection 'Guidelines' that mentions PR
+tags will also be extended (a hyperlink will be added) to refer to this
+guideline, since it also contains guidelines about use of tags.
Review Comment:
> I expect "the list" to contain just high-priority set of enforced items and few recommendations, so that we can focus what's essential. I don't expect it to be a long document, if we can make it as a paragraph and a couple of small lists. I'd like to make it as easier and accessible as possible for new contributors to understand quickly.
100% agreed - I hated reading long documents too. An agile OSS should prefer concise guidelines that are to-the-point, instead of tedious unnecessarily long ones :-)
--
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
[GitHub] [tvm-rfcs] junrushao1994 commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
junrushao1994 commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949461034
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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)
Review Comment:
I don't actually have a strong opinion :-) Let's just clarify it a little bit so that readers could better follow
--
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
[GitHub] [tvm-rfcs] leandron commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1224165355
@areusch can you have a final look and merge if you're happy, before creating the `[VOTE]` thread you mentioned?
--
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
[GitHub] [tvm-rfcs] manupak commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
manupak commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1227649858
Ah ok, just noticing that it was missing in the RFC header
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947337486
##########
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
Review Comment:
@tkonolige I'll added that to the CMG (Commit Message Guideline). But just to clarify, did you mean camel case (or even upper camel case) instead of snake case? I think snake case would be for instance [bug_fix]...
--
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
[GitHub] [tvm-rfcs] areusch merged pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
areusch merged PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88
--
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
[GitHub] [tvm-rfcs] tqchen commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
tqchen commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946001132
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
Review Comment:
It might be good to allow a bit of flexibility here. As testcases together with changes also have its own set of benefits (in reducing the overall overhead of crafting a PR) and allow us to focus on the most important part -- the message itself being descriptive
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946250351
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
Review Comment:
I'm not sure. As committer I agree to fixing minor deviations (a period in the end of a commit title, for instance), that's ok. However ignoring deviations is not fine, ignoring _minor_ deviations is fine. The enforced rules are not minor deviations, having a PR without a body (which will result in a commit message in the main tree without a body) is not a minor deviation. On the other hand a period in the end of the commit title is a minor deviation, but what else can be considered a minor deviation? I'm certainly appealing to the community's good faith and will when interpreting this part. In general I would prefer the committer -- if she/he so wishes -- to let the minor deviations pass and **remind** the author, so helping to educate the contributors, than having committers spending cycles fixing such a minor deviations.
--
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
[GitHub] [tvm-rfcs] areusch commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
areusch commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1215326331
@gromero thanks for sending the RFC! let's leave it open for a few days for discussion, then I will create a `[VOTE]` GH issue.
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949924952
##########
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:
Fine by me. I agree with the spelling suggested by @tkonolige. Marking this as resolved.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by 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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946234962
##########
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
Review Comment:
I'm open to suggestion. I don't have any strong idea other than trying to establish a common set of acceptable tags, -- if that's even possible, but not sure how.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946240326
##########
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;
Review Comment:
In my experience, I don't recall about the use of present tense being used in the commit message title. The imperative mood is the best choice in my opinion and is the common practice on lots of open source projects that I can think of.
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946484612
##########
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:
Yes, I agree with @gromero. I don't think this should be 100% prescriptive on every minimal - sometimes cosmetic - detail, so I think the original wording is OK.
--
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
[GitHub] [tvm-rfcs] slyubomirsky commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
slyubomirsky commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946028214
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
+changes having one commit for the fix and another one for the test, applying the
+rules and recommendations in this guideline to each commit.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. The only
+recommendation is that if the additional commits render the PR title and/or body
+outdated then the PR title and body must reflect the new changes in the code and
+be updated accordingly (remember that the PR title and body will be used to
+compose the final commit message that will land in the main tree).
Review Comment:
Committers have the ability to edit others' messages, I believe, so would it be incumbent on the committer who is merging the PR to ensure the topic post is up-to-date?
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949306373
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. However if the
+additional commits render the PR title and/or body outdated then it's the
+author's responsibility to keep the PR title and body in sync with new changes
+in the code and updated the PR title and body accordingly (remember that the PR
+title and body will be used to compose the final commit message that will land
+in the main tree).
+
+Committers will seek to fix any issues with the commit message prior to
+committing but they retain the right to inform the author of the rules and
+encourage them to follow them in future. Also, they retain the right to ask to
+the author to update the PR title and/or body when they are not correctly
+updated or fixed.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+TVM Community must reach a certain concensus about the rules in this guideline,
+hence this RFC will be voted.
+
+Once it's voted and approved the Commit Message Guideline text will be added to
+`./docs/contribute/pull_request.rst` doc, under section 'Submit a Pull Request',
+below subsection 'Guidelines', as a subsection named “Commit Message Guideline”.
+The text in the second-last item in subsection 'Guidelines' that mentions PR
+tags will also be extended (a hyperlink will be added) to refer to this
+guideline, since it also contains guidelines about use of tags.
Review Comment:
Marking this a resolved. Please reopen in case there are any additional point.
--
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
[GitHub] [tvm-rfcs] junrushao1994 commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
junrushao1994 commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949466177
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
Review Comment:
That makes a lot of sense to me! Thank you for the clarification!
--
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
[GitHub] [tvm-rfcs] areusch commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
areusch commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1220078234
@junrushao1994 i would love for tvm-bot to enforce this as much as possible. some items are going to be more challenging than others. the thing i think we'd really like is for tvm-bot to handle merging, so that we consistently remember to copy the PR body into the git commit body. we've been debugging some auth problems with that which we're unable to reproduce locally; this has been unfortunately quite tricky to track down due to not known the organization's default GitHub Actions token settings. hopeful we can get a resolution on that and then move towards making "tvm-bot merge" a thing.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946271861
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
Review Comment:
I agree we don't should encourage implicitly the practice of putting multiple changes in a PR, in the sense of multiple non-related changes. But because it's not possible to merge the patchsets without squashing them that's sometimes hard to avoid multiple commits in a PR, and, moreover, it's even desirable to have them -- I think -- to ease the review. But you are right, and tad in the sense as we discussed in the Community meeting, it's hard to point / or capture in the guideline a maximum number of commits or the boundaries about which set in the patchset should go in to a PR and which go into another PR. So as I said below when replying to @tqchen @leandron I think we can remove this paragraph yep.
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946486015
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
Review Comment:
Yes, I agree we can remove the paragraph.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r952765859
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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)
Review Comment:
@junrushao friendly ping :)
--
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
[GitHub] [tvm-rfcs] junrushao1994 commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
junrushao1994 commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r948522271
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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
Review Comment:
Do we want to have a finite set of tags (so that the bot could potentially recognize and categorize them) or give more flexibility to developers?
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. However if the
+additional commits render the PR title and/or body outdated then it's the
+author's responsibility to keep the PR title and body in sync with new changes
+in the code and updated the PR title and body accordingly (remember that the PR
+title and body will be used to compose the final commit message that will land
+in the main tree).
+
+Committers will seek to fix any issues with the commit message prior to
+committing but they retain the right to inform the author of the rules and
+encourage them to follow them in future. Also, they retain the right to ask to
+the author to update the PR title and/or body when they are not correctly
+updated or fixed.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+TVM Community must reach a certain concensus about the rules in this guideline,
+hence this RFC will be voted.
+
+Once it's voted and approved the Commit Message Guideline text will be added to
+`./docs/contribute/pull_request.rst` doc, under section 'Submit a Pull Request',
+below subsection 'Guidelines', as a subsection named “Commit Message Guideline”.
+The text in the second-last item in subsection 'Guidelines' that mentions PR
+tags will also be extended (a hyperlink will be added) to refer to this
+guideline, since it also contains guidelines about use of tags.
Review Comment:
My takes: I would love to recommend that those rules be numbered, and written in one concise sentence with an positive/negative example each, so those could be the items the reviewers refer to.
For example:
```Rule R1. PR Title
- R1.1. Use uppercase for the first letter of the PR title, as well as acronyms, but anything else should be lowercased.
✅ This is a PR title
❌ THIS IS a pR tiTLE
- R1.2. Do not use any period at the end of the title.
✅ PR title without period
❌ PR title with a period.
```
I'm happy to work together on drafting this if you guys think it's a right direction to go :-)
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
Review Comment:
To clarify, does the "bullet commit message" mean the messages generated by GitHub squash merge? e.g.
```
This is a PR title (#123)
* upd
* save
* fix
* done
```
On the contrary, this is encouraged to have commit messages like:
```
This is PR title (#123)
This PR introduces the following changes:
* Add more flexibility to `Schedule.cache_read`
* Fix a bug in the original `cache_read` implementation with a regression test added
* Polish the doc to make it more readable
```
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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)
Review Comment:
Just to clarify, we only use uppercase for the first letter and acronyms right? This means:
```
Fix TVM use of OpenCL library
```
is better than
```
Fix TVM Use of OpenCL Library
```
--
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
[GitHub] [tvm-rfcs] gromero commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1218386487
OK, I agree @leandron @driazati Thanks.
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949305309
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. However if the
+additional commits render the PR title and/or body outdated then it's the
+author's responsibility to keep the PR title and body in sync with new changes
+in the code and updated the PR title and body accordingly (remember that the PR
+title and body will be used to compose the final commit message that will land
+in the main tree).
+
+Committers will seek to fix any issues with the commit message prior to
+committing but they retain the right to inform the author of the rules and
+encourage them to follow them in future. Also, they retain the right to ask to
+the author to update the PR title and/or body when they are not correctly
+updated or fixed.
+
+# Reference-level explanation
+[reference-level-explanation]: #reference-level-explanation
+
+TVM Community must reach a certain concensus about the rules in this guideline,
+hence this RFC will be voted.
+
+Once it's voted and approved the Commit Message Guideline text will be added to
+`./docs/contribute/pull_request.rst` doc, under section 'Submit a Pull Request',
+below subsection 'Guidelines', as a subsection named “Commit Message Guideline”.
+The text in the second-last item in subsection 'Guidelines' that mentions PR
+tags will also be extended (a hyperlink will be added) to refer to this
+guideline, since it also contains guidelines about use of tags.
Review Comment:
I think it would be great too, as the list as you describe is easier to point out in reviews, and also for authors to checklist their patches.
I expect "the list" to contain just high-priority set of enforced items and few recommendations, so that we can focus what's essential. I don't expect it to be a long document, if we can make it as a paragraph and a couple of small lists. I'd like to make it as easier and accessible as possible for new contributors to understand quickly.
--
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
[GitHub] [tvm-rfcs] manupak commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
manupak commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1227600044
Just a final remark : dont we need a tracking issue to track actual landing of the PR that adds pull_request.rst to docs ?
--
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
[GitHub] [tvm-rfcs] tqchen commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
tqchen commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946750210
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
Review Comment:
I agree this can be a different guideline
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949291606
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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
Review Comment:
I'm marking this as resolved.
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947557070
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
Review Comment:
Marking this as resolved, as the paragraph was removed.
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949314370
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
Review Comment:
@mbaret friendly ping.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949670019
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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)
Review Comment:
@junrushao1994 That's right, i.e. form `Fix TVM use of OpenCL library` is better than form `Fix TVM Use of OpenCL Library`. But since in the RFC we used exactly the best form, i.e. `Fix TVM use of OpenCL library`, as the example I'm not sure how we could clarify further ... but wait, hm I think I get it, what can be ambiguous is that when it says "uppercase for the first letter" it can also be interpreted as the first letter of each word is capitalized, i.e. it can be interpreted as title case (https://en.wikipedia.org/wiki/Title_case), right? If so we should clarify saying explicitly it's uppercase for the first letter in the title and that title case must be avoided? Am I following you correctly?
--
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
[GitHub] [tvm-rfcs] driazati commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
driazati commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1218337517
> Moreover, because typically (in GH for instance) the PR (title and body) is auto-generated from the initial commit messages, if you apply the guidelines to these commits you kill two birds with one stone: you get a nice PR "for free" and also help the review.
(this isn't really a comment on this RFC since it's more about implementation details) This is a bit of a back and forth with committers / PR authors. As @leandron said it's ultimately the committer's responsibility to ensure that the final commit message (which is presented to them on GitHub when clicking "Squash and Merge") is of high quality. GitHub will auto-fill out that box with the commit messages so an author carefully rebasing their PR commit messages to match their PR title and body can ensure that it is going to be good, but I think that'd be difficult to coordinate across all contributors.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r948483949
##########
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
Review Comment:
@leandron @tkonolige Tags are marked as "enforced" I'm not totally convinced of it, but I don't strongly oppose to that. If we want to keep this way I think just the presence of tags must be enforced, not the capitalization etc. Also, the bullet on tags starts with "Check if a tag should be present as a hint...", if it's indeed enforced that must be chanced, since it would not be optional. PTAL.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r948480835
##########
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
Review Comment:
Addressed here: https://github.com/apache/tvm-rfcs/pull/88/commits/8486cc76cd7b76b244af02b561c889bfce95ea37
--
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
[GitHub] [tvm-rfcs] leandron commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1227607913
> @leandron @gromero
> Just a final remark : dont we need a tracking issue to track actual landing of the PR that adds pull_request.rst to docs ?
We do, I think we can create that once voting is finished.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947362309
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
+changes having one commit for the fix and another one for the test, applying the
+rules and recommendations in this guideline to each commit.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. The only
+recommendation is that if the additional commits render the PR title and/or body
+outdated then the PR title and body must reflect the new changes in the code and
+be updated accordingly (remember that the PR title and body will be used to
+compose the final commit message that will land in the main tree).
Review Comment:
Addressed here: https://github.com/apache/tvm-rfcs/pull/88/commits/afcbb981155b5a7eaf99c8306ee1cd2fb33aa463
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949299170
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
Review Comment:
To reinforce the original intent of the RFC, the bullet commit guidance is merely a recommendation. I suppose that as in any text, the `*` signed would be used where you need an unordered list, and that's ok IMHO.
My expectation is that if we get commits described with meaningful phrases stating the work done, and it happens to be a bullet list, it is still a step forward from what we have now.
--
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
[GitHub] [tvm-rfcs] mbaret commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
mbaret commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r950206516
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
+changes having one commit for the fix and another one for the test, applying the
+rules and recommendations in this guideline to each commit.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. The only
+recommendation is that if the additional commits render the PR title and/or body
+outdated then the PR title and body must reflect the new changes in the code and
+be updated accordingly (remember that the PR title and body will be used to
+compose the final commit message that will land in the main tree).
Review Comment:
seems good - will leave to @slyubomirsky to mark as resolved though given it's his chain.
--
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
[GitHub] [tvm-rfcs] gromero commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1235612896
@areusch @driazati @tqchen @tkonolige @manupak @Lunderberg @mbaret @junrushao @Hzfengsy @slyubomirsky @ekalda thanks a lot for the reviews and support of this RFC!
Tracking issue is created at: https://github.com/apache/tvm/issues/12690
Cheers.
--
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
[GitHub] [tvm-rfcs] gromero commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1215257266
@tqchen @jroesch @driazati @areusch @Mousius @manupak @tkonolige @mbaret @leandron @alanmacd
--
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
[GitHub] [tvm-rfcs] gromero commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1215988221
> Can you also include guidelines for 1. how the PR author can update their commits if they are not up to this standard (rebase?)
Let's say a PR has just been created. The idea is that regarding the commit message (that will compose the final commit message) it doesn't matter the commit(s) message(s) of the commits used to create the PR. It really only matters the PR's title and body. So rather than a rebase + push force it's just a matter of updating the PR's title and body in the GH GUI.
Now, I believe you are thinking of the case when the author's commits are a rather difficult (like, quite badly organized) set of patches and the PR's title and body also don't help to understand the change. Since it's the "initial" commits (the PR has just been created), I think that it would be awesome that the author would reorganize it, splitting the commits in a reasonable way, then rebase and push again it, updating the PR title and body (or even creating a brand new PR) that would ease the review. That's what I tried to capture here in this part: https://github.com/apache/tvm-rfcs/pull/88/commits/99c3bc2247050eb1d8ef3ed6ab665d455cfd4c1a#diff-759e47e77c87b8e4c14dba43c17bac829cbb502e9369211c1ad751253dae57f5R126 but merely **a recommendation**, moreover now we have to consider also the comment from Matthew about multiple in a PR:
https://github.com/apache/tvm-rfcs/pull/88#discussion_r946033889
Personally, I don't want people to stuff a bunch of non-related commits into a PR, but, on the other hand I also think it helps me review the changes when the commits are split in reasonable way -- just for a single self-contained feature / change -- even if they will be squashed before merge (which is a pity I might say). But capturing such a nuances in the guideline in very case is hard.
> 2. How reviewers should handle squashing an merging (should they copy text from the PR description or from a commit)
I tried to address it right in the beginning here:
https://github.com/apache/tvm-rfcs/commit/99c3bc2247050eb1d8ef3ed6ab665d455cfd4c1a#diff-759e47e77c87b8e4c14dba43c17bac829cbb502e9369211c1ad751253dae57f5R46-R50
and then in the end here:
https://github.com/apache/tvm-rfcs/commit/99c3bc2247050eb1d8ef3ed6ab665d455cfd4c1a#diff-759e47e77c87b8e4c14dba43c17bac829cbb502e9369211c1ad751253dae57f5R138-R139
i.e. they should copy text from the PR description, title and body.
>3. how to handle commits that fix linting or formatting issues in the original PR.
Do you mean the additional commits that are pushed to the branch as a consequence of the review process right? The ones we've been calling "additional commit messages"? If so, here is where I tried to address it:
https://github.com/apache/tvm-rfcs/commit/99c3bc2247050eb1d8ef3ed6ab665d455cfd4c1a#diff-759e47e77c87b8e4c14dba43c17bac829cbb502e9369211c1ad751253dae57f5R134-R135
i.e. it doesn't matter. All that matters for the final commit message that lands into the main tree is to keep the PR's title and body updated and following the Commit Message Guideline.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947163678
##########
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:
@leandron I guess what I meant is that I think @tkonolige suggestion of s/No period at the end of the title is necessary/Do not put a period at the end of the title/ is fine, but I think we should not enforce it. Are you ok if we change to the suggested wording but don't marked it as a "enforced" rule? I think the form suggested is a tad stronger but won't be 100% prescriptive if not marked as enforced.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947163678
##########
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:
@leandron I guess what I meant is that I think @tkonolige suggestion of s/No period at the end of the title is necessary/Do not put a period at the end of the title/ is fine, but I think we should not enforce it. Are you ok if we change to the suggested wording but don't marked as "enforced"? I think the form suggested is a tad stronger but won't be 100% prescriptive if not marked as enforced.
--
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
[GitHub] [tvm-rfcs] driazati commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
driazati commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1226673013
> @driazati notes that GitHub [just introduced](https://github.blog/changelog/2022-08-23-new-options-for-controlling-the-default-commit-message-when-merging-a-pull-request/) new options for controlling the default commit messages, so hopefully we can leverage that to implement the merge and complement that with a lint tool.
This setting looks like it includes `@` tags from PRs in the default commit message which may make it a non-starter for us since that generates a lot of notifications
--
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
[GitHub] [tvm-rfcs] leandron commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1222334914
I think most comments are addressing implementation details of what it being proposed here. There is not really any opposition to move forward with what is being proposed here.
@areusch you suggested to create a [VOTE] thread with this proposal? I guess we're ready to go?
Also wanted to highlight that despite this looking to be _a set of enforced_ rules, in practice it is just trying to guarantee that we have the bare minimum in terms of tracking the changes in git with a title and textual description of the change being made. Nothing too far from what is enforced in any relevant open-source project.
--
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
[GitHub] [tvm-rfcs] areusch commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
areusch commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1233535253
The vote has passed, therefore I'll merge this RFC. @gromero please create a tracking issue (you can create another PR to add it to this doc).
--
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
[GitHub] [tvm-rfcs] tkonolige commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
tkonolige commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r945960620
##########
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
Review Comment:
How should multiple tags be handled? `[BugFix,CI]` or `[BugFix][CI]`. Can we also have guidelines on capitalization here?
##########
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:
How about "Do not put a period at the end of the title"
--
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
[GitHub] [tvm-rfcs] mbaret commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
mbaret commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946029912
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
Review Comment:
I think we might even want the exact opposite guidance here - a fix should always come with a test case otherwise we don't know that anything's been fixed.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946240326
##########
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;
Review Comment:
In my experience, I don't recall about the use of present tense in the commit message title. The imperative mood is the best choice in my opinion and is the common practice on lots of open source projects that I can think of.
--
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
[GitHub] [tvm-rfcs] tkonolige commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
tkonolige commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1217226784
@gromero I think I am getting a little confused at the difference between messages in the commits composing the PR and the final commit in main. To make things clearer, I think it would help to refer to to commit title and commit message as PR title and PR description, respectively. PR title and PR description are the things that the PR author and the reviewers will be discussing (which will become the commit title and message).
To clarify, these guidelines do not apply to the individual commits (on the authors branch) that compose the PR?
> i.e. they should copy text from the PR description, title and body.
I think we should explicitly say that whoever is merging the PR needs to copy the description of the PR into the commit message (unless we have changed GitHub to do this automatically?). Having clear instructions (like how to copy formatting) for mergers would be really nice.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949670019
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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)
Review Comment:
@junrushao1994 That's right, i.e. form `Fix TVM use of OpenCL library` is better than form `Fix TVM Use of OpenCL Library`. But since in the RFC we used exactly the best form as the example, i.e. `Fix TVM use of OpenCL library`, I'm not sure how we could clarify further ... but wait, hm I think I get it, what can be ambiguous is that when it says "uppercase for the first letter" it can also be interpreted as the first letter of each word is capitalized, i.e. it can be interpreted as title case (https://en.wikipedia.org/wiki/Title_case), right? If so we should clarify saying explicitly it's uppercase for the first letter in the title and that title case must be avoided? Am I following you correctly?
--
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
[GitHub] [tvm-rfcs] tkonolige commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
tkonolige commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949365935
##########
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
Review Comment:
I don't think capitalization necessarily matters, it would just be nice to have a recommendation.
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947547443
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
Review Comment:
@tqchen can you check and mark this as resolved if applicable?
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949312742
##########
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
Review Comment:
@driazati can you comment?
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r951569041
##########
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;
Review Comment:
@leandron Since @slyubomirsky but a thumbs up on my comment I'm mark it as resolved. Feel free to reopen it if that's not the case. Thanks.
--
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
[GitHub] [tvm-rfcs] areusch commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
areusch commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1226442023
I created a [vote thread](https://github.com/apache/tvm/issues/12583) to broadcast this more broadly to the community. Please signal your support there.
@driazati notes that GitHub [just introduced](https://github.blog/changelog/2022-08-23-new-options-for-controlling-the-default-commit-message-when-merging-a-pull-request/) new options for controlling the default commit messages, so hopefully we can leverage that to implement the merge and complement that with a lint tool.
--
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
[GitHub] [tvm-rfcs] slyubomirsky commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
slyubomirsky commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946026034
##########
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;
Review Comment:
Would simple present tense not also work? "Adds feature X," "updates image Y," etc. Is the use of the imperative a firmly established norm?
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947540167
##########
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:
Yes, I don't think should be enforced.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947364076
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
Review Comment:
Addressed here: https://github.com/apache/tvm-rfcs/pull/88/commits/b7ee4c7432a1f24f6304751af4acd3a4e2139512
--
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
[GitHub] [tvm-rfcs] gromero commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1217357505
> @gromero I think I am getting a little confused at the difference between messages in the commits composing the PR and the final commit in main. To make things clearer, I think it would help to refer to to commit title and commit message as PR title and PR description, respectively. PR title and PR description are the things that the PR author and the reviewers will be discussing (which will become the commit title and message).
I tried to keep consistent throughout the text the following meanings:
A commit message is comprised of a commit title and body (body is the same term used, for instance, on `git-format` manual to refer to that part of the commit)
The final commit message is composed of the PR title and body, i.e. the final commit message title = PR tile and final commit message body = PR body. When one creates a PR from, let's say, a single commit, that's the default.
> To clarify, these guidelines do not apply to the individual commits (on the authors branch) that compose the PR?
Most importantly these guidelines apply to the PR title and body, since that's what will be used to compose the final commit message that gets committed to the main tree. But that's also applicable to the commits used to initially create the PR, since a good commit messages naturally helps the reviewer. Moreover, because typically (in GH for instance) the PR (title and body) is auto-generated from the initial commit messages, if you apply the guidelines to these commits you kill two birds with one stone: you get a nice PR "for free" and also help the review.
As the review develops (e.g. if changes are requested by the reviewers), all that's necessary is to keep the PR title and body in sync with the code changes.
> > i.e. they should copy text from the PR description, title and body.
>
> I think we should explicitly say that whoever is merging the PR needs to copy the description of the PR into the commit message (unless we have changed GitHub to do this automatically?). Having clear instructions (like how to copy formatting) for mergers would be really nice.
@leandron @areusch @mbaret @driazati wdyt?
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947554612
##########
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;
Review Comment:
@slyubomirsky the intention when proposing this guidance, is to **enforce** (_meaning it blocks a PR to be merged_) the really minimal that we don't have today.
That's why we don't want to be 100% prescriptive with enforced rules. Let's get the basics right (meaning we have commit messages that are more meaningful than e.g. `fix bug`, `cleanup` or `lint code`) and then we can evolve this gradually.
Based on this, let us know if you're ok to proceed this way (Marking this as resolved when you agree), or you have any other question.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949688496
##########
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:
Addressed here: https://github.com/apache/tvm-rfcs/pull/88/commits/bb5936e231b2f0f4f156c73f5ac2fc15ba4794fe @leandron @tkonolige PTAL.
--
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
[GitHub] [tvm-rfcs] driazati commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
driazati commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1220859744
> i would love for tvm-bot to enforce this
We can also enforce whatever rules as part of lint, #12367 has an example implementation for what we could do
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949313271
##########
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;
Review Comment:
@slyubomirsky friendly ping.
--
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
[GitHub] [tvm-rfcs] Hzfengsy commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
Hzfengsy commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r952716801
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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)
Review Comment:
```suggestion
- RFC PR: [apache/tvm-rfcs#0088](https://github.com/apache/tvm-rfcs/pull/88)
```
--
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
[GitHub] [tvm-rfcs] driazati commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
driazati commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r948534241
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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
Review Comment:
We have some soon to be released work about our issue tags that may also help. It would be nice to align to the categories in https://github.com/apache/tvm/blob/main/CONTRIBUTORS.md so there is a clear mapping of tag -> responsible person. I think the tags should probably not be a fixed list though (but we could have some auto-warning on a PR when a tag is used that isn't in the `CONTRIBUTORS.md` list). Either way the set of tags to be used should be an implementation detail of this PR
--
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
[GitHub] [tvm-rfcs] Lunderberg commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
Lunderberg commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1233170752
[Rendered link](https://github.com/gromero/tvm-rfcs/blob/cmg/rfcs/0088-commit-message-guideline.md)
--
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
[GitHub] [tvm-rfcs] slyubomirsky commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
slyubomirsky commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946035804
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
+changes having one commit for the fix and another one for the test, applying the
+rules and recommendations in this guideline to each commit.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. The only
+recommendation is that if the additional commits render the PR title and/or body
+outdated then the PR title and body must reflect the new changes in the code and
+be updated accordingly (remember that the PR title and body will be used to
+compose the final commit message that will land in the main tree).
Review Comment:
I guess it would be easier for the committers to request updates from the author before merging
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r951616228
##########
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
Review Comment:
@tkonolige Thanks for the clarification. @leandron since all the approvals for this RFC was with the text that had tag presence as "enforced" I think are all aligned that it should be kept as such -- like in the original proposal. But given @tkonolige comment above, I just made a bit clearer that the capitalization is not enforced with this commit here: https://github.com/apache/tvm-rfcs/pull/88/commits/32527cf74bbdb8999b5a6ccc417292c56f574dda So I'm marking this conversation as resolved. If that's not the case, please reopen. Thanks!
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949308190
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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)
Review Comment:
The example reflects a few variants, do you want us to include the particular one you suggest?
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946234962
##########
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
Review Comment:
I'm open to suggestions. I don't have any strong idea other than trying to establish a common set of acceptable tags, -- if that's even possible, but not sure how.
--
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
[GitHub] [tvm-rfcs] tkonolige commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
tkonolige commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947295360
##########
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
Review Comment:
I would do snake case and multiple brackets `[BugFix][CI]` as those seem to be the most used (from skimming the first page of open PRS).
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949288645
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
+changes having one commit for the fix and another one for the test, applying the
+rules and recommendations in this guideline to each commit.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. The only
+recommendation is that if the additional commits render the PR title and/or body
+outdated then the PR title and body must reflect the new changes in the code and
+be updated accordingly (remember that the PR title and body will be used to
+compose the final commit message that will land in the main tree).
Review Comment:
@mbaret can you have a look and mark it as resolved In case you agree, or propose a suggestion in case this needs further improvement?
--
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
[GitHub] [tvm-rfcs] leandron commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r949299170
##########
rfcs/0088-commit-message-guideline.md:
##########
@@ -0,0 +1,187 @@
+- 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. If more than one tag
+ exist, multiple brackets should be used, like [BugFix][CI]. The case
+ recommended for tags, in geral, is the upper camel case. For example, prefer
+ the forms [Fix], [BugFix], and [Docker] instead of [fix], [bug_fix], and
+ [docker]. Acronyms should be kept as such so, for example, use [CI] and [TVMC]
+ instead of [ci] and [tvmc]. 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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
Review Comment:
To reinforce the original intent of the RFC, the bullet commit guidance is merely a recommendation. I suppose that as in any text, the `*` sign would be used where you need an unordered list, and that's ok IMHO.
My expectation is that if we get commits described with meaningful phrases stating the work done, and it happens to be a bullet list, it is still a step forward from what we have now.
--
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
[GitHub] [tvm-rfcs] gromero commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r947340379
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
Review Comment:
@mbaret I see. Would adding "Committers are encouraged to fix those minor deviations before merging the PR" work? If not, please suggest an alternative :)
--
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
[GitHub] [tvm-rfcs] gromero commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
gromero commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1215261260
@areusch @leandron Could you please help me on how to trigger a [VOTE] thread on this RFC? Cheers.
--
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
[GitHub] [tvm-rfcs] mbaret commented on a diff in pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
mbaret commented on code in PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#discussion_r946031070
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
Review Comment:
If it's minor, could we advise the committer fixes it in addition to reminding the author? The current language suggests ignoring the deviation would also be fine.
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
+a fix and so it also adds a regression test, it’s a good practice to split the
+changes having one commit for the fix and another one for the test, applying the
+rules and recommendations in this guideline to each commit.
+
+After a new PR is created and the review starts it’s common that reviewers will
+request changes. Usually the author will address the reviewers’ comments and
+push additional commits on top of the initial ones. For these additional commits
+there is no recommendation regarding the commit messages. The only
+recommendation is that if the additional commits render the PR title and/or body
+outdated then the PR title and body must reflect the new changes in the code and
+be updated accordingly (remember that the PR title and body will be used to
+compose the final commit message that will land in the main tree).
Review Comment:
I'd say ideally we want it to be the author's responsibility, otherwise this will end up always been left to the committer. That being said, the committer should always seek to fix any issues prior to committing but they should retain the right to inform the author of the rules and encourage them to follow them in future. We probably need more explicit language around the author/committer responsibilities.
##########
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.
+
+_PR/commit body_:
+
+* Guarantee a body exists (enforced);
+* Don’t use Github usernames in body text, like @username (enforced);
+* Avoid “bullet” commit message bodies: “bullet” commit message bodies are not
+ bad per se, but “bullet” commit messages without any description or
+ explanation is likely as bad as commits without any description, rationale,
+ or explanation in the body.
+
+For minor deviations from these guidelines, the community will normally favor
+reminding the contributor of this policy over reverting or blocking a commmit /
+PR.
+
+Commits and PRs without a title and/or a body are not considered minor
+deviations from these guidelines and hence must be avoided.
+
+Most importantly, the contents of the commit message, especially the body,
+should be written to convey the intention of the change, so it should avoid
+being vague. For example, commits with a title like “Fix”, “Cleanup”, and
+“Fix flaky test” and without any body text should be avoided. Also, for the
+review, it will leave the reviewer wondering about what exactly was fixed or
+changed and why the change is necessary, slowing the review.
+
+Below is an example that can be used as a model:
+
+> [microTVM] Zephyr: Remove zephyr_board option from build, flash, and open_transport methods
+>
+> Currently it’s necessary to pass the board type via ‘zephyr_board’ option to
+> the Project API build, flash, and open_transport methods.
+>
+> However, since the board type is already configured when the project is
+> created (i.e. when the generate_project method is called), it’s possible to
+> avoid this redundancy by obtaining the board type from the project
+> configuration files.
+>
+> This commit adds code to obtain the board type from the project CMake files,
+> removing this option from build, flash, and open_transport methods, so it’s
+> only necessary to specify the ‘zephyr_board’ option when calling
+> generate_project.
+>
+> This commit also moves the ‘verbose’ and ‘west_cmd’ options from ‘build’
+> method to ‘generate_project’, reducing further the number of required options
+> when building a project, since the ‘build’ method is usually called more often
+> than the ‘generate_project’.
+
+If a PR is created from more than one commit (a patchset), then ideally the
+changes should be split into commits in a reasonable way. For instance, if it’s
Review Comment:
This seems out-of-scope of this RFC. I don't think we should implicitly encourage the practice of putting multiple changes in a PR, or at least if we do want to encourage that it should need a separate vote.
--
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
[GitHub] [tvm-rfcs] leandron commented on pull request #88: [RFC] Add Commit Message Guideline
Posted by GitBox <gi...@apache.org>.
leandron commented on PR #88:
URL: https://github.com/apache/tvm-rfcs/pull/88#issuecomment-1217692311
> > I think we should explicitly say that whoever is merging the PR needs to copy the description of the PR into the commit message (unless we have changed GitHub to do this automatically?). Having clear instructions (like how to copy formatting) for mergers would be really nice.
>
> @leandron @areusch @mbaret @driazati wdyt?
It is a responsibility of the _author_ to keep the GitHub PR title and description consistent with the work done. That's just basic housekeeping. It is a responsibility of the _committer_, by the time the GitHub PR is ready to be merged, to make sure a message exists and is same, then copy the PR description and set as contents of the commit message the will be done in the git repository.
This RFC is not describing _how_ people should do their work. It is merely creating a baseline for what is acceptable to maintaining a healthy repository with tracking of commits that contains a description of the changes being made.
> Having clear instructions (like how to copy formatting) for mergers would be really nice.
It is out of scope for this specific RFC text to have such information (as in a _step-by-step_ guide here). These guidelines you suggest are implementation details that we can do in many ways, prior to officially communicating committers about this new rule - when it comes to effect.
--
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