From 79d51babae2873dc1e743a4e3d2632a7f4ade695 Mon Sep 17 00:00:00 2001 From: Robert Ancell Date: Tue, 7 Nov 2023 14:28:00 +0200 Subject: [PATCH] Don't require formatting for commit titles, these cause more problems than they solve. Adding the type/scope to the commit title is a bad idea for the following reasons: Encoding data in the title indicates a problem in the tooling. If you need to clearly tag commits with information, then PR tags should probably be used. These are much more easily filtered in a UI. Categories, while familiar to people, are generally a bad way of labelling data. You can fit the majority of cases into categories but there will always be cases where no category fits (which means either using no category, a general category or adding many infrequently used categories). Data also often falls into multiple categories. This can be handled by listing multiple categories for the data (i.e. treating as tags) or having to decide a threshold when a category is met. Due to these reasons picking categories is time consuming task without always a clear solution. Having a code change, title and type/scope means you now have three things that need to be consistent. The risk of them not matching is increased over just having two. A good analogy for this is code comments. The general modern consensus on comments is they should be used sparingly, and only in cases where the intention of the code can't be easily determined. If you have a comment that just literally states what the code does it is useless (this is the same for a PR title where the words match the type/scope). If you have to use a comment it is an indication that you should consider how your code is written. Rewriting the code often makes the comment redundant (the same for PR titles - if you need to add the type/scope then perhaps the title is not appropriately descriptive for the change). With all the above issues there are likely to be many errors setting the type/scope which quickly undermines confidence in them. I have experienced this in many projects that use them. --- project-repo/review-process.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/project-repo/review-process.md b/project-repo/review-process.md index 27fd5af9..3bba07af 100644 --- a/project-repo/review-process.md +++ b/project-repo/review-process.md @@ -31,21 +31,6 @@ We should use the **merge commit workflow** (not squash and merge). The history Individual commits do not follow [conventional commits][convcommits] and are free form. However, for better readability of the mainline, the merge commit in the mainline should follow [conventional commits][convcommits]. -For this, the PR title should be of the form: `(): `. The scope is optional. The first comment will be the commit body and needs to reference any associated JIRA card on the last line, separated by a blank line. - -The accepted `types` are: - -* `build`: Changes that affect the build system or external dependencies -* `ci`: Changes to the CI configuration -* `deps`: Update dependencies -* `docs`: Documentation only changes -* `feat`: A new feature -* `fix`: A bug fix -* `maint`: Changes that do not affect the meaning of the code (white-spaces, formatting, missing semi-colons, typo fixes, etc). Gardening… -* `perf`: A code change that improves performance -* `refactor`: A code change that neither fixes a bug nor adds a feature (nor add bugs)! -* `tests`: Adding missing tests or correcting existing tests - > TODO: have a document defining what to configure in every new GitHub project (webhook for Jira, merge commit + default commit template, automated merged branch deletion). ## Process