This is an automated email from the ASF dual-hosted git repository.
leandron pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm.git
The following commit(s) were added to refs/heads/main by this push:
new 85bf80c822 [Docs] Add Commit Message Guideline (#12689)
85bf80c822 is described below
commit 85bf80c822ec930939eabba1dd8a774c88d88bdd
Author: Gustavo Romero <[email protected]>
AuthorDate: Wed Sep 7 04:00:24 2022 -0300
[Docs] Add Commit Message Guideline (#12689)
This commit adds the Commit Message Guideline text to Apache TVM
documentation in ./docs/contribute/pull_request.rst, 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 is also updated to refer
to this guideline.
This documentation will help guide contributors on how to write good
commit messages when submitting code / creating Pull Requests, in
accordance with RFC-0088:
https://github.com/apache/tvm-rfcs/blob/main/rfcs/0088-commit-message-guideline.md
---
docs/contribute/pull_request.rst | 113 ++++++++++++++++++++++++++++++++++++++-
1 file changed, 112 insertions(+), 1 deletion(-)
diff --git a/docs/contribute/pull_request.rst b/docs/contribute/pull_request.rst
index 81852a2126..7b5509be0a 100644
--- a/docs/contribute/pull_request.rst
+++ b/docs/contribute/pull_request.rst
@@ -62,7 +62,12 @@ Guidelines
- Add test-cases to cover the new features or bugfix the patch introduces.
- Document the code you wrote, see more at :ref:`doc_guide`
- `Create a pull request
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request>`_
and fix the problems reported by CI checks.
-- Request code reviews from other contributors and improve your patch
according to their reviews by ``@``-ing them in your pull request. Tags in PR
titles will automatically tag subscribed users, so make sure to put relevant
topics in your PR titles (e.g. ``[microTVM] a cool change`` and not ``a cool
change for microTVM``).
+- Request code reviews from other contributors and improve your patch according
+ to their reviews by ``@``-ing them in your pull request. Tags in PR titles
+ will automatically tag subscribed users, so make sure to put relevant topics
+ in your PR titles (e.g. ``[microTVM] Add a cool change`` and not ``a cool
change for microTVM``).
+ Please see the Commit Message Guideline below on the guidelines about the
tags
+ in a PR/commit title and how to write good PR/commit messages.
- To get your code reviewed quickly, we encourage you to help review others'
code so they can do the favor in return.
- Code review is a shepherding process that helps to improve contributor's
code quality.
@@ -72,6 +77,112 @@ Guidelines
- The PR can be merged after the reviewers approve the pull request.
+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);
+ - A tag must be present as a hint about what component(s) of the code
+ the PRs / commits “touch” (enforced). 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;
+ - 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”;
+ - Do not put a period at the end of the title.
+
+*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.
+
CI Environment
--------------
We use Docker images to create stable CI environments that can be deployed to
multiple machines.
