commit messages

[code reader]

since the upgrade from cvs to svn, it became practical and reasonable to merge changesets from the 3.0 branch to the trunk, and sometimes, i would guess, in the other direction also.
however, merges have their own little idiosyncrasies, and one that imho is not handled well currently is the commit messages.
10 out of the last 14 commits to the trunk have a commit message that says simply "merge".
this is not helpful, and will be of little use to anyone looking at the tree three weeks, three months or three years from now.

true, those commits are merges, but this piece of information is at most marginally helpful.
the lease that's required (again, imho) for such a commit message to be considered useful is to include the revision id# of the merge source.
even better would be to duplicate the commit message of the original commit, (i.e., the commit from which the merge is derived), in addition to the word merge and the original revision ID.
something like:

merge revision XXXX: bla bla bla

where the bla bla are a copy 'n paste of the original commit.
if one merge cover more than one (source) commit, use a multi-line message.
imho, this would make the repo more sane.

as usual, just my 2c.

[Acyd Burn]

This will solve itself once we upgrade the repository to version 1.5 which support merge tracking.

[code reader]

Don't want to make myself more of a PITA than i already am, but would it be too much to ask to do it manually until the time you upgrade to 1.5?
thx.

[code reader]

on second thought, if the commit messages looks like this:

Revision 8777

davidmj, 08/22/2008 07:00 AM

“There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult.” – Charles Antony Richard Hoare

This has been tested fairly well… Post/topic insertion/deletion appears to work very well, moving has yet to be tested with much rigor…
Files
added
modified
deleted

/branches/posting/phpBB/develop/posting-api.php
/branches/posting/phpBB/includes/db/postgres.php

then maybe we are better off if you just put "merge" in the merge commit message.
this commit message has zero value. it doesn't tell us if this commit fixed a bug, added a feature or changed a behavior, let alone more specific details like "what was the bug", "what is the feature", "what behavior changed, from what to what, and how to test it".

to add insult to injury, it seems that 2 completely unrelated changes are bundled in one commit: change to the posting api, together with a change to postgresql dbal implementation.

of course, it is your sandbox, and you can play in it any way you want, but it is my humble opinion that you completely discount any value commit messages may have. in this case, you might want to save yourself some time and just use empty commit message. this is easy enough by using -m "" on the command line...

in my experience, commit messages can be pretty useful tool, if they are taken seriously and follow some agreed-upon rules.
they can be used to derive a "what changed", and give a person going over the repo some sense of who is doing what.

i'm not saying that all the commit messages in phpbb repo are useless. however, because it seems that you never agreed on a standard, there is a wide variety. "dumdidum", "meh" or "Let's try to keep the lid on the jar" may have some entertainment value, but it tends to fade with time, and these definitely do not provide any help to anyone going over the repo and trying to understand what's going on and where the ship is sailing.

[Highway of Life]

I thought it was quite clear what he said: He completely revamped the posting api to be simpler so that there were no obvious deficiencies.
The enhancement consisted of improved posting, topic insertion and deletion. Only that he didn't test the move capability yet.
And that is all derived without reading any of the committed code.

[DavidMJ]

on second thought, if the commit messages looks like this:

Revision 8777

davidmj, 08/22/2008 07:00 AM

“There are two ways of constructing a software design: One way is to make it so simple that there are obviously no deficiencies, and the other way is to make it so complicated that there are no obvious deficiencies. The first method is far more difficult.” – Charles Antony Richard Hoare

This has been tested fairly well… Post/topic insertion/deletion appears to work very well, moving has yet to be tested with much rigor…
Files
added
modified
deleted

/branches/posting/phpBB/develop/posting-api.php
/branches/posting/phpBB/includes/db/postgres.php

then maybe we are better off if you just put "merge" in the merge commit message.
this commit message has zero value. it doesn't tell us if this commit fixed a bug, added a feature or changed a behavior, let alone more specific details like "what was the bug", "what is the feature", "what behavior changed, from what to what, and how to test it".

to add insult to injury, it seems that 2 completely unrelated changes are bundled in one commit: change to the posting api, together with a change to postgresql dbal implementation.

of course, it is your sandbox, and you can play in it any way you want, but it is my humble opinion that you completely discount any value commit messages may have. in this case, you might want to save yourself some time and just use empty commit message. this is easy enough by using -m "" on the command line...

in my experience, commit messages can be pretty useful tool, if they are taken seriously and follow some agreed-upon rules.
they can be used to derive a "what changed", and give a person going over the repo some sense of who is doing what.

i'm not saying that all the commit messages in phpbb repo are useless. however, because it seems that you never agreed on a standard, there is a wide variety. "dumdidum", "meh" or "Let's try to keep the lid on the jar" may have some entertainment value, but it tends to fade with time, and these definitely do not provide any help to anyone going over the repo and trying to understand what's going on and where the ship is sailing.

First off, the postgres change is quite relevant. If you cannot see that, there is little I can do for you.
Second off, if you don't understand what I am doing you do not have to pay attention. My branch is just for little ol' me so that I can check my code in from one place and check it out from another.

[Acyd Burn]

i'm not saying that all the commit messages in phpbb repo are useless. however, because it seems that you never agreed on a standard, there is a wide variety. "dumdidum", "meh" or "Let's try to keep the lid on the jar" may have some entertainment value, but it tends to fade with time, and these definitely do not provide any help to anyone going over the repo and trying to understand what's going on and where the ship is sailing.

Honestly, do not read them then. It is still our repository and no one is forced to read the comments. Furthermore, the private branches (davids posting and now my acydburn one) are solely for the dev, so he is free to do whatever he/she wants... as long as he/she is able to follow it everything is fine.

(Of course there should be correct merge messages, but we are lazy often)

[Acyd Burn]

this commit message has zero value. it doesn't tell us if this commit fixed a bug, added a feature or changed a behavior, let alone more specific details like "what was the bug", "what is the feature", "what behavior changed, from what to what, and how to test it".

ideally, a comment would only state a number... fixed bug #xxxx, completed task #ixxxx - that's it. A comment is not an explanation, the code is.

[code reader]

My branch is just for little ol' me so that I can check my code in from one place and check it out from another.

you are right and i apologize for "picking" on a commit that really belongs to a "semi private" branch.

i should have picked a commit message from the trunk or the main (3.0.0) branch for my example.
my bad.

however, i want to clarify what i mean:
i do not seek to aggravate phpbb team with my criticism.
i was trying to suggest that adopting a "standard" form for commit message is useful, and it makes just as much sense to do so as it does to standardize coding style.

this is what i found in my years of software development, and it's what several OS projects use. it's not an imperative, merely a suggestion. sorry if i tend to sound confrontational - that's my problem, not yours...

ideally, a comment would only state a number... fixed bug #xxxx, completed task #ixxxx

sure. every project should decide what's "ideally" for them. my point was that in the long run, picking a "template" and sticking to it is beneficial.
btw, many projects use more than one such "template": commit message for a bug fix looks different than commit message for a feature add, for example.

again, i apologize to david for "picking" on him. private branches should be exempt from project-wide standards.

[Highway of Life]

What benefit would a project wide standard on commit messages have? I’m genuinely curious because to me, a commit message is nothing more than a very simple summary of the commit unless it was a security or bug fix, in which case it would simply be #xxxx
If I want to find out what the code does, I would read through the diff from the commit log. How is sticking to a standard template for commit messages going to benefit the users and developers? Remember that the SVN is really only for those who are following development, which means you can read the code already.