[RFC] FreeCAD commit history formatting ideas

[Kunda1]

As this FreeCAD 'engine' evolves and we have more developers with commit permissions updating the FreeCAD core ( ), it makes sense to me that we start applying a standard commit message format so it's easy to differentiate what workbench or portion of the FreeCAD core is being altered/modified.
The average commit looks something like this (again emphasis on average)

[Workbench] brief commit message no longer than X chars

Do we want to use this square bracket format around the workbench name ? Or are there other thoughts around this?

[openBrain]

In the extent of my experience, square brackets are good because they have a good visibility in the message. However they are not so easy to catch on the keyboard, what can be "boring" when you have a lot to use. It can be envisaged to replace them with parenthesis "()" or chevrons "<>".

Also following this discussion, it could be a good idea that if the commit is worth appearing in the release notes, the message is prepended with a dedicated tag (eg. <BugFix> or <FeatureAdd> or ..., you probably have to define a short list of them).
Obviously in this case, it shall always be considered regarding the latest release. I.e. if you introduce a new feature (tagged <FeatureAdd>) then discover a bug and fix it in the same dev cycle, you won't prepend the patching commit with <BugFix> to prevent duplicate entry in release notes.

My 2 cents.

[mlampert]

I think this is good for PRs but too much overhead for commit messages. I can't come up with any value/use for it neither. On the PR it let's the respective committer know "this is for you, buddy", but on a single commit?

[wandererfan]

I think this is good for PRs but too much overhead for commit messages. I can't come up with any value/use for it neither. On the PR it let's the respective committer know "this is for you, buddy", but on a single commit?

+1.

[triplus]

As a general guideline, commit messages shouldn't be too long. Some git tools complain, when you start creating too long commit message. Using some special formatting in commit messages could therefore likely go against such guidelines. We could decide to not follow such guidelines.

Anyway, i have a feeling Label (GitHub) was design for such purposes in the first place. And AFAIK it is already being used by people having write access, to organize their review process? Long story short, people having write access and doing the actual review should say if they need some additional formatting or are OK with how things work ATM. And if Label functionality still suffices for such purposes. In addition such things are usually guidelines and not rules. Therefore PR creator in the end has the freedom to choose the sensible thing to do.

[Kunda1]

FreeCAD is growing exponentially right now. I agree with @microelly2 that FreeCAD is an engine. I'm thinking that it makes sense in order to view the git history in a convenient way...but obviously not introduce too much rigidity.

Lets hear from the core devs too, when they get a moment to read this thread.

[bernd]

I have started years ago to add a preface to my commit messages:

- FEM (may be 95 %)
- Material (2 %)
- Arch (2 %)
- Base, CMake, ... (1 %)

ahh this one is the best https://github.com/FreeCAD/FreeCAD/comm ... c7cc14e2db

[triplus]

I agree with @microelly2 that FreeCAD is an engine.

I lean more towards FreeCAD being a CAD framework.

Lets hear from the core devs too, when they get a moment to read this thread.

I agree. If they care i guess we can care after too.

ahh this one is the best https://github.com/FreeCAD/FreeCAD/comm ... c7cc14e2db

YEAH 1000 commits for great FreeCAD project ahh the commit ... FEM: netgen mesh obj, typo in attribute description

Realistically this likely is a rather not ideally formatted PR commit message. If most PR commit messages would be like that we would likely need to do something about it. As they are in general rather sensible formed maybe we are trying to fix a non existing issue? Anyway, if somebody would like to use a prefix in squared brackets, fell free to do that. If not, that is OK too. If somebody reaches a milestone and would like to have a special PR message, we are rather open to that too. Just try not to exaggerate!

[abdullah]

Mostly, I prepend the WB name to the commit.

Sometimes I indicate whether it refers to the App or Gui.

I do this so that it is easy to identify what is being touched from the git log. If several commits are present in a PR, it also helps identify commits that touch places I generally do not commit to, such as freecad core.

I admit I am not fully consistent though.

I think there should be some leeway for the developer though. While standardisation may bring advantages, developers are generally rather sensitive to style topics. It is probably too much of a burden to force every single commit to follow a pattern. Developers will arc like cats if too much overhead is put into perceived lower value style matters

In any case, most developers are very focused in working area. If I see bernd, I directly assume its FEM, if I see wandererfan I assume is TechDraw (at least currently). My commits are mostly sketcher. What might make some sense is that we mark the commits that are outside our normal working area... maybe... just some idea.

[wmayer]

Lets hear from the core devs too, when they get a moment to read this thread.

For me it's not of much use when we have a prefix on the commit message because when I go through the commits logs in GH then usually I know in which directory I have to search and look at its history. Then I usually find very quickly what I search for.

IMO it's up to everybody to add a prefix or not.