A suggestion to add the keyword `Update` about git-commit-message

[joelparkerhenderson]

Thank you for the suggestion. What's your opinion of what the word "Update" would do to semantic versioning? For example, is "update" a major version increment, or a minor version increment, or a patch version increment, etc.?

[stevencychuang]

Hi,

I would like to choose a patch version increment for Update.
Because the use case is similar to Fix, Bump, and Optimize.
For the example Update the test case data, it is neither to change the APIs, architectures, nor function features.
Feel free to discuss if you have any suggestions.

Cheers,
Steven

[joelparkerhenderson]

I would like to choose a patch version increment for Update.

Semantic versioning tends to favor more-specific reasons . An update can be major (e.g. API breaking change), minor (e.g. API addition), patch (e.g. no API change but code change such as a bug fix).

Think of your example "Update the test case data", or any example you want.

Why, more specifically, is someone doing the update?

Try this a few levels deep, such as... the update to the test case data is happening because ... which is because ... which is because ... (this idea is sometimes called "5 whys" or "root cause").

[stevencychuang]

Semantic versioning tends to favor more-specific reasons . An update can be major (e.g. API breaking change), minor (e.g. API addition), patch (e.g. no API change but code change such as a bug fix).

The term Update often refers to the cases that just extend data or replace the old information with new one. For example, apt-get update will just update repository information but not change the behavior of apt-get, but apt-get upgrade might change the behavior because the dependencies changed. Therefore, I would like to use the term Upgrade rather than Update for major version. In most specific cases, I would like to use Drop or Stop.
For the cases of minor version, I would like to use Add rather than Update. Because Add is more specific for the definition of minor version add functionality.

Think of your example "Update the test case data", or any example you want.

Why, more specifically, is someone doing the update?

Try this a few levels deep, such as... the update to the test case data is happening because ... which is because ... which is because ... (this idea is sometimes called "5 whys" or "root cause").

The example "Update the test case data", can refer to update test cases that are more fitting user scenarios. The case should not change the function behavior.

[joelparkerhenderson]

Thanks for the explanations. I believe that you may want to look at semantic versioning, and how it favors tracking major versions, minor versions, and patch versions.

Semantic versioning handles things significantly differently than you describe, because semantic versioning emphasizes breaking changes (i.e. major versions) as compared to addition changes (i.e. minor versions) as compared to fix changes (i.e. patch versions).

For these git commit message word recommendations, any "Drop" is automatically a semantic major version change, because we use "Drop" to mean the removal of existing functionality.

For these git commit message word recommendations, any "Add" is automatically a semantic minor version change, because we use "Add" to mean the addition of new functionality.

For these git commit message word recommendations, any "Fix" is automatically a semantic patch version change, because we use "Fix" to mean the adjustment of something that isn't working as documented. The word recommendations for "Refactor" and the other "R" words are also for patch version changes.

When you write this: "The term Update often refers to the cases that just extend data or replace the old information with new one." then what I'm suggesting is that a good git commit message is best when it explains a deeper reason, akin to a deeper "why" such as in 5 whys.

If you discover that existing data was wrong, or broken, or incomplete, or expired, or needs adjusting for refactoring, then you can write a message that starts with "Fix" or "Refactor" etc. that emphasizes why the patch is needed (rather than emphasizing the data).

If you discover that a new feature or capability is helped by adding more data, then you can write a message that starts with "Add" and emphasizes the new feature or capability (rather than emphasizing the data).

If you discover that user-facing functionality needs to be removed, and that involves changing the data, then you can write a message that starts with "Drop" and emphasizes why the removal is happening (rather than emphasizing the data).

Your example of apt does make sense to me, because I use it often. I also use similar package managers. But apt options tend to favor broad strokes, rather than semantic versioning. For example, my most-important need for apt-get for my stable production systems is to ensure that the system does get security fixes, but does not get any other changes.

How do you tell apt to just do security upgrades, similar to semantic versioning patches?

Here's what I do; there may be better ways.

apt-get -s dist-upgrade | grep "^Inst" | 
    grep -i securi | awk -F " " {'print $2'} | 
    xargs apt-get install

The code above is one reason (of many) why apt-get has challenges doing incremental fixes, as well as reproducible builds. Many developers are shifting from package managers such as apt-get to declarative reproducible builds, such as by using containers (e.g. Docker) or virtual machine configurations (e.g. Packer) or separation of concerns (e.g. Nix).

Of course, semantic versioning is not perfect. Many software offerings don't follow it perfectly. Still, it's better than many other approaches IMHO.

I hope this info is helpful... see what you think, and if you're able to dig deeper into the reasons for your updates and upgrades. Ideally think of adjusting from "what is changing" (e.g. a data update) to "why is this changing" (e.g. for removal of a capabilties, or addition of a capability, or a bug fix or refactor, etc.).

[joelparkerhenderson]

I haven't seen a reply in a few weeks, so I'll close this issue; if you want, you can reopen it, and share more of your perspective. Thanks!