As a developer, I need rules what to include in commit messages.

[poikilotherm]

This is triggered by #5377 and commits from #5341.

As far as I can see from the dev docs, there is no standard or rule what to include in commit messages and what not, besides asking for inclusion of the GH issue number.

This is not always possible, as a solution for an issue is often done by multiple commits. IMHO just including an internal ticket number from an unknown JIRA is not sufficient. IMHO this should be rejected by QA in the future.

I could add some bits of this in a PR right away, but as I am not part of QA or core dev team, that seems inappropriate. Open for discussion - I would love feedback on this to enhance my own commit messages, too.

[pdurbin]

@poikilotherm this is what we say at http://guides.dataverse.org/en/4.9.4/developers/version-control.html#commit-your-change-to-your-new-branch

"Making a commit (or several commits) to that branch. Ideally the first line of your commit message includes the number of the issue you are addressing, such as Fixed BlockedApiPolicy #3728."

So we do talk about multiple commits. If you'd like to offer better wording, please consider making a pull request. At the very least "Making" should be "Make". Thanks!

[poikilotherm]

Sorry @pdurbin I missed the "several commits" part. Should we be a bit more explicit about this and give an example?

GitHub also understands things like "Relates" and "Solves" and "Fixes". Maybe intermediate commits should state "Relates to #xxx" and the final solution then "Solves #xxx"?

But the biggest issue is about what should be put in the git log besides the issue number. IMHO it should be a single line with a short paraphrase first and ideally, in case of more complex things done or things left open/vague a longer explanation including references below.

Example: 8e24d98

IMHO details should live inside the git log and not in the PR / issue comments, as this is way to much info in these places (and it might get lost...). A commit should always be self explanatory, so if you look at it a year or two later, you can understand why the change was necessary. Sometimes even "trivial" changes might be caused by or trigger big issues. git blame comes in handy with a detailed log, too.

[pdurbin]

@poikilotherm if your main point is that developers should feel free to include a "body" in their commit messages (separated by a newline from the subject) then I definitely agree with you. Please feel free to make a pull request about this.

As you know, Dataverse developers also communicate with each other with by adding to the Developer Guide. Obviously, you'll be editing the dev guide when you make a pull request for this issue. To me the dev guide is more lasting than commit messages, though both are important. They have different purposes.

I try to remember to put the issue number in the subject of all commits. I don't use "fixes #xxx" because I don't want GitHub to close issues when I push. I want QA to close issues after the branch has been tested.

I hope this helps.

[poikilotherm]

Looks like this is nothing too many people care about. 🤷 Closing for cleanup.