On 08/01/20 00:19, Artem Shchygel wrote:

Hi, All

In this RFC we're proposing slight changes to Git commit message format to make it more informative and more friendly for automation tools.

Here is the list of changes proposed

1. Start subject line with the tag that describes nature of the commit. List of tags is as follows:
- **fix:** For commits that are fixing the bug
- **feat:** For commits that introduce a new feature
- **imp:** For commits that introduce improvement of the existing code logic without changing functionality
- **doc:** For commits that don't change code logic but deal with documentation (including adding comments, fix spelling, etc.)
- **style:** For commits that don't change code logic but deal with coding style (indents, whitespaces, etc.)
- **chore:** For commits that don't affect output target (like changes to CI scripts)
Having tagged commits will help closed source maintainers to decide which commits to cherry-pick for projects that are in "maintenance mode" as opposite to "active development mode"

Hints are very welcome, but not in subject lines. Please use

Name: value
Name: value # comment

style tags near the end of the commit messages instead.

Subject lines are primarily for human readers. And because edk2 has long
filenames, and we're supposed to include package names and component
names in subject lines, hardly any space is left for actual meaningful
subjects. CVE identifiers are the only exceptions (they *should* be
mentioned in subjects lines; and PatchCheck.py already permits more
characters in subjects that contain CVE identifiers).

2. Remove "Package/Module" reference from subject line. Since subject line length is limited it's better to be allocated for commit description which is more important

I'm opposed to this. "Package/Module" is the absolute key by which I
orient myself for determining impact / maintainership relevance /
regression risk. I regularly browse the git history for new commits, and
I entirely orient myself after the Package/Module prefixes.

3. Remove "CVE" number from subject line for the same reason. CVE number (if present) should be placed on separate line after long description (see example below)

I agree that mentioning CVE IDs in subject lines is an exceptions. I
could let go of that, if contributors were *very* disciplined about
stating CVE IDs properly in commit messages.

4. Add optional tag to the long description. List of tags is as follows:
- **[BREAKING CHANGE]:** For commits that break backward compatibility
- **[SECURITY FIX]:** For commits that fix known security vulnerability

Explicitly stating such traits is very welcome (even if not with this
specific format, perhaps) in commit message bodies.

5. Move bugzilla reference to separate line after long description and (possible) CVE line (see example below). This move follows the logic of evaluation of commit nature (read subject, if unclear read long description, if still unclear see bugzilla)

Bugzilla numbers should already be stated as:

Ref: https://bugzilla.tianocore.org/show_bug.cgi?id=2129

or

Link: https://bugzilla.tianocore.org/show_bug.cgi?id=2129

or

Bugzilla: https://bugzilla.tianocore.org/show_bug.cgi?id=2129

tags.

An example would be:
```
imp: Short one line description of change

Several lines of
description for the
change.

REF:https://bugzilla.tianocore.org/show_bug.cgi?id=1000

Signed-off-by: Contributor Name <contributor@...>
Reviewed-by: Reviewer Name <reviewer@...>
```

A CVE example would be:
```
fix: Short one line description of change

[SECURITY FIX]: Several lines of
description for the
change.

CVE-2018-12180

REF:https://bugzilla.tianocore.org/show_bug.cgi?id=2000

Signed-off-by: Contributor Name <contributor@...>
Reviewed-by: Reviewer Name <reviewer@...>
```

I entirely support including as much information as possible in commit
messages; if we can do that in machine readable format, that's even
better. But subject lines are not the place; the commit message bodies are.

I recommend the "Name: value" and "Name: value # comment" formats, but
don't insist on those.

What really matters to me is that we don't litter subject lines with
machine-readable artifacts.

Obviously: this is just my personal opinion.

Thanks
Laszlo