From 15c75ebead23760de1be6ffed3ca591c2f16d03f Mon Sep 17 00:00:00 2001 From: Pedro Eugenio Rocha Pedreira Date: Fri, 25 Oct 2024 16:56:39 -0700 Subject: [PATCH] docs: Add conventional commit specification guildelines (#11356) Summary: Add guildelines to the CONTRIBUTING doc about PR titles and description, with the purpose of improving our ability to classify commits and navigate project history. Fixes: https://github.com/facebookincubator/velox/discussions/11039 Differential Revision: D65005411 --- CONTRIBUTING.md | 69 ++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 63 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 84d5a6083b07f..bcb43029b0f80 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,11 +83,8 @@ The contribution process is outlined below: * Always follow the [coding best practices](#coding-best-practices) outlined below. * If the change is large, consider posting a draft Github pull request (PR) with the title prefixed with [WIP], and share with collaborators to get early feedback. - * Give the PR a clear, brief description; when the PR is - merged, this will be retained in the extended commit message. Check out - [How to Write Better Git Commit Messages – A Step-By-Step Guide](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/) - and [How to Write a Git Commit Message](https://cbea.ms/git-commit/) to - learn more about how to write good commit messages. + * Ensure the PR follows the [title and description + guidelines](#commit-messages) presented below. * Make sure the PR passes all CI tests. * Create/submit a Github PR and tag the reviewers identified in Step 3. @@ -109,6 +106,66 @@ The contribution process is outlined below: maintainer. At this point, a Meta employee will be notified to merge your PR, due to tooling limitations. +## Commit Messages + +We build Velox for the long-run, and to do so it is crucial that project +maintainers are able to efficiently inspect and understand project logs. + +Commit messages that follow a strict pattern improve maintainability, and allow +tasks such as summarizing changelogs and identifying API breaking changes to be +automated. Despite requiring more rigor from authors and reviewers, consistency +creates productivity in the long term. + +In Velox, commit messages are generated based on the input provided to PRs, and +must follow the [conventional commit +specification](https://www.conventionalcommits.org/en/v1.0.0/) in the following +manner: + +**PR titles** must follow the pattern: + +> [optional scope]: + +where: + +* *Type* can be any of the following keywords: + * **feat** when new features are being added. + * **fix** for bug fixes. + * **build** for build or CI-related improvements. + * **docs** for enhancements to documentation (only). + * **refactor** for refactoring (no logic changes). + +* PR titles also take an *optional scope* field containing the area + of the code being target by the PR, to further help commit classification. + For example, "fix(expression): " or "refactor(parquet): " or "feat(memory):". + It is ok to omit this field if there is no adequate classification for the + PR, or if the PR touches multiple different components. + +* A *description* sentence summarizing the PR, written in imperative tone. The + description must be capitalized, not contain a period at the end, and be kept + under a 80 characters limit. + +Examples of PR titles are: + +* feature(type): Add support for IPPREFIX type +* fix: Prevent unnecessary flatmap to map conversion +* refactor(vector): Use 'if constexpr' for Buffer::is_pod_like_v + +The **PR body** must contain a summary of the change, focusing on the *what* +and *why*. Keep columns at 80 characters. + +**Breaking API Changes.** A "BREAKING CHANGE:" footer must be added to PRs +that break backwards compatibility of any external API in Velox, followed by a +sentence explaining the extent of the API change. This means either API changes +that may break client builds, or semantic changes on the behavior of such APIs. + +If there is a Github Issue or Discussion related to the PR, authors must also add a +"Fixes: " section to the bottom of the PR body. + +To learn more about how to write great commit messages, check out these resources: + +* [How to Write Better Git Commit Messages – A Step-By-Step Guide](https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/) +* [How to Write a Git Commit Message](https://cbea.ms/git-commit/) + ## Coding Best Practices When submitting code contributions to Velox, make sure to adhere to the @@ -208,7 +265,7 @@ with a benchmark. line arguments. ``` - # Test the new function in isolation. Use --only flag to restrict the set of functions +# Test the new function in isolation. Use --only flag to restrict the set of functions # and run for 60 seconds or longer. velox_expression_fuzzer_test --only --duration_sec 60 --logtostderr=1 --enable_variadic_signatures --velox_fuzzer_enable_complex_types --velox_fuzzer_enable_decimal_type --lazy_vector_generation_ratio 0.2 --velox_fuzzer_enable_column_reuse --velox_fuzzer_enable_expression_reuse