Commit log

[Ged]

I think we all agree that the process of filling out a changelog is a task
we would rather avoid.

Collibri has made some efforts to alleviate this and despite getting some
good results we're also seeing a lot of information which isn't changelog
oriented. This now leaves us with a new problem of having to manually go
through data output from Collibri's tool and reformat it.

This is arguably more time consuming than the original method and isn't
working for us in its current form.

The current problem with this method is that a commit log is not a changelog
and getting something which can be classed as a changelog from this without
human intervention is an impossible task. There are also some people who
would rather write their own changelog instead of allowing a tool to
generate it for you.

The problem as I see it is two fold :

-          Commit messages generally contain cryptic message, humour, idioms
and frustration

-          Patches can spread over a wide range of modules making it
difficult to insert them into the correct position in the changelog.

A possible solution to this is to wrap up a changelog in XML elements. Such
a commit log would be as follows :

............................................................................
..........................

- Stop mixing unicode and ANSI strings

- Don't dereference NULL pointers

<changelog>

<notepad>Converted the application to Unicode</notepad>

<user32>Fixed a crash highlighted via  adobe acrobat</user32>

</changelog>

............................................................................
..........................

This will allow anyone who wants to have a changelog autogenerated at
release time to take advantage and anyone who wants to do their own to
ignore it.

The problem with this method lies in getting the XML tags correct.

Anyone have any other ideas?

Ged.

[Marc Piulachs]

I think using xml is very impractical , commit messages are intended to be written and consumed by humans; generating, mixing and validating machine friendly content (in this case xml) with taht it's not a good idea. We can use a more simple aproach like adding a special keyword that identifies a commit message sentence as a potential changelog message. For example:

- Content 
- Stop mixing unicode and ANSI strings (@notepad)

- Don't dereference NULL pointers (b:999@user32)

- More content

This content can then be parsed with a simple regular expression to auto generate the changelog as follows:

- Notepad

-  Stop mixing unicode and ANSI strings (GED) (rev 123-3/07/2009)

USER32

- (BugFix see 999), Don't dereference NULL pointers (GED) (rev123-3/07/2009)

Regards,

/Marc

From: Ged 
Sent: Friday, July 03, 2009 3:30 PM
To: [e-mail] 
Subject: [ros-dev] Commit log

I think we all agree that the process of filling out a changelog is a task we would rather avoid.

Collibri has made some efforts to alleviate this and despite getting some good results we're also seeing a lot of information which isn't changelog oriented. This now leaves us with a new problem of having to manually go through data output from Collibri's tool and reformat it.

This is arguably more time consuming than the original method and isn't working for us in its current form.

The current problem with this method is that a commit log is not a changelog and getting something which can be classed as a changelog from this without human intervention is an impossible task. There are also some people who would rather write their own changelog instead of allowing a tool to generate it for you.

The problem as I see it is two fold :

-          Commit messages generally contain cryptic message, humour, idioms and frustration

-          Patches can spread over a wide range of modules making it difficult to insert them into the correct position in the changelog.

A possible solution to this is to wrap up a changelog in XML elements. Such a commit log would be as follows :

......................................................................................................

- Stop mixing unicode and ANSI strings

- Don't dereference NULL pointers

<changelog>

<notepad>Converted the application to Unicode</notepad>

<user32>Fixed a crash highlighted via  adobe acrobat</user32>

</changelog>

......................................................................................................

This will allow anyone who wants to have a changelog autogenerated at release time to take advantage and anyone who wants to do their own to ignore it.

The problem with this method lies in getting the XML tags correct.

Anyone have any other ideas?

Ged.

--------------------------------------------------------------------------------

_______________________________________________
Ros-dev mailing list
[e-mail]
http://www.reactos.org/mailman/listinfo/ros-dev

[Sarocet]

Ged wrote:
> I think we all agree that the process of filling out a changelog is a
> task we would rather avoid.
>
> Collibri has made some efforts to alleviate this and despite getting
> some good results we’re also seeing a lot of information which isn’t
> changelog oriented. This now leaves us with a new problem of having to
> manually go through data output from Collibri’s tool and reformat it.
>
> This is arguably more time consuming than the original method and
> isn’t working for us in its current form.
>
> The current problem with this method is that a commit log is not a
> changelog and getting something which can be classed as a changelog
> from this without human intervention is an impossible task. There are
> also some people who would rather write their own changelog instead of
> allowing a tool to generate it for you.
>
> The problem as I see it is two fold :
>      Commit messages generally contain cryptic message, humour,
>
> idioms and frustration
>      Patches can spread over a wide range of modules making it
>
> difficult to insert them into the correct position in the changelog.
>
> A possible solution to this is to wrap up a changelog in XML elements.
> Such a commit log would be as follows :
>
> ......................................................................................................
>
> Stop mixing unicode and ANSI strings
>
> Don’t dereference NULL pointers
>
> <changelog>
>
> <notepad>Converted the application to Unicode</notepad>
>
> <user32>Fixed a crash highlighted via  adobe acrobat</user32>
>
> </changelog>
>
> ......................................................................................................
>
> This will allow anyone who wants to have a changelog autogenerated at
> release time to take advantage and anyone who wants to do their own to
> ignore it.
>
> The problem with this method lies in getting the XML tags correct.
>
> Anyone have any other ideas?
>
> Ged.

XML is not too friendly for manually writing.
What about:

......................................................................................................

- Stop mixing unicode and ANSI strings

- Don’t dereference NULL pointers

Changelog:

Notepad: Converted the application to Unicode

User32: Fixed a crash highlighted via  adobe acrobat</user32>

......................................................................................................

[Aleksey Bragin]

> Changelog:
>
> Notepad: Converted the application to Unicode
>
> User32: Fixed a crash highlighted via  adobe acrobat</user32>

First of all, those should be two different commits. Then, in this  
case it's almost Wine's style, but with unnecessary capitalisation of  
the first letter in module's name.

As for my opinion about XML, I didn't really fully get it, but if I  
have to type that manually in an svn commit log message, that'd be  
annoying.

WBR,
Aleksey Bragin.

[Ged]

The XML example was to try to highlight the difference between the commit
message and the corresponding changelog message.
I agree XML isn't practical, but we need something along these lines. A
simple colon will easily confuse a parser.

As for being in two different commits, this was just an example of an
extreme case to highlight that a commit isn't always attributable to a
single diff.
I was going to use Mm and Ke as an example (this is much more likely) but I
wanted to clearly show what I meant and people might not have picked up on
the difference between those.

Ged.

-----Original Message-----
From: [e-mail] [mailto:[e-mail]] On
Behalf Of Aleksey Bragin
Sent: 03 July 2009 16:27
To: ReactOS Development List
Subject: Re: [ros-dev] Commit log
> Changelog:
>
> Notepad: Converted the application to Unicode
>
> User32: Fixed a crash highlighted via  adobe acrobat</user32>

First of all, those should be two different commits. Then, in this  
case it's almost Wine's style, but with unnecessary capitalisation of  
the first letter in module's name.

As for my opinion about XML, I didn't really fully get it, but if I  
have to type that manually in an svn commit log message, that'd be  
annoying.

WBR,
Aleksey Bragin.
_______________________________________________
Ros-dev mailing list
[e-mail]
http://www.reactos.org/mailman/listinfo/ros-dev

[victor martinez]

I like Ged idea, but maybe it would be more flexible using:
..........................................
FRUSTATING MESSAGE

<notepad>Converted the application to Unicode@bugXXXX</notepad>
FRUSTRATING MESSAGE2
 <user32>Fixed a crash highlighted via  adobe
acrobat</user32>
............................................Why i like this approach?:

*Open and close HTML tags helps to be sure the Commiter wrote a correct Module.
*The Script could be written to understand <notepad>Blablalba</notepfasdfasdfadfa>.
Script would check both Tags and if they arent the same, then it will compare with the list of modules. 
If one of the Tags exists then the line will be written in that Module. This avoids small errors as <notepad>bla</notpad>If none exists or both exists then the line will be dropped and an Email sent to the commiter.

*I think the <changelog> Tag isnt needed since it´s obvious which lines has to go to the Changelog(those between Tags)
*Maybe we can use the script to send a comment to the Bugzilla Bugreport asking for retesting when a Bug number is added.

*************************************************About the other ideas:
-Using the "First capital letter" plus a ":" as Sarocet suggest is too easy to confuse.You can create a Frustation Message as "WTF Boys: Dont you know C?".Or forget the "capital" or the ":" in a sentence which has to go to the changelog.
-About Marc Piulachs idea, i think it is quite nice too, btw is needed a "Bug" reference as he suggest.

That is my 2 cents
Víctor Martínez

_________________________________________________________________
Descubre todas las formas en que puedes estar en contacto con amigos y familiares.
http://www.microsoft.com/windows/windowslive/default.aspx

[Sarocet]

victor martinez wrote:
> About the other ideas:
>
> -Using the "First capital letter" plus a ":" as Sarocet suggest is too
> easy to confuse.You can create a Frustation Message as "WTF Boys: Dont
> you know C?".
>
> Or forget the "capital" or the ":" in a sentence which has to go to
> the changelog.

That's why I also keeped "Changelog:", as a magic word to enter into
changelog parsing mode :)
You can allow any casing, though.

PS: I hope the script doesn't find any WTF Boys module in svn. ;-)

[KJK::Hyperion]

Ged wrote:
> <changelog>

No XML. XML sucks. And knowing all modules in the tree by name sucks as
well. Module names can be extracted automatically, and the changelog
line copied for each of them, because if the change affects multiple
modules, then it's relevant to all of them

Set a commit message template property for the tree that suggests where
to put the text that should go in the changelog and how to tell apart
from the rest, and leave it at that. The odd commit that doesn't fit the
template can be edited by hand, or ignored altogether for the purposes
of the changelog ("formatting fix", "revert revision", "fix build" etc.)

My suggestion for the template is:

<changelog line>
<bug numbers, comma-separated>
--
<detailed commit message, insults, Arch bashing>

For smartasses like me who'll want to affect several modules at once but
with a different changelog line for each, provide an override syntax:

[module 1] <changelog line for module 1>
<changelog line for module 1>
<changelog line for module 1>
...
[module 2] <changelog line for module 1>
...
<bug numbers>
--
<detailed commit message>

Want to get even fancier?

[module 1, module 2] <changelog line for module 1 and 2>
[module 3] <changelog line for module 3 and 4>
[module 4] ditto
...

All of which is extremely easy to parse with a script. A message that
doesn't contain some magic string ("--", or maybe something more
distinctive), or that contains some magic string ([formatting],
[revert], etc.) will be ignored

[KJK::Hyperion]

KJK::Hyperion wrote:
> For smartasses like me who'll want to affect several modules at once but
> with a different changelog line for each, provide an override syntax:
>
> [module 1] <changelog line for module 1>

And module names should be stored in SVN as metadata, so that I can look
them up in a place that makes sense

[Colin Finck]

Looking at all the presented ideas so far, I currently like KJK's one most,
just with two little comments:

KJK::Hyperion wrote:
> My suggestion for the template is:
>
> <changelog line>
> <bug numbers, comma-separated>

For the bug format, let's just stick to what TSVN uses.
On the one side, we have this little bug text box at the top right of the
commit dialog, which most developers use for ages. Due to our repository
settings, it will automatically add "See issue #1234 for more details" at
the end of the commit. On the other side, TSVN also seems to detect every
number prefixed with "bug" as a valid bug number (see for example r41739).
I guess that algorithm would be easy to implement in the script and devs
wouldn't need to change their way of adding bug numbers.
> And module names should be stored in SVN as metadata, so that I can look
> them up in a place that makes sense

Well, you can already look up the module names in the .rbuild files, can't
you? If there are currently mismatches between the .rbuild names and the
ones in the changelog, we should stick to the names in the .rbuild files in
the future.
In my opinion, putting them into SVN metadata just creates duplicate data
with the risk of being out of sync.

Best regards,

Colin

[Aleksey Bragin]

On Jul 3, 2009, at 9:02 PM, KJK::Hyperion wrote:
> My suggestion for the template is:
>
> <changelog line>
> <bug numbers, comma-separated>
> --
> <detailed commit message, insults, Arch bashing>

The summary + detailed commit message idea has some benefits (one of  
them goes to the changelog for example).

Insulting various people in commit messages (fortunately, that turns  
out to be Arch quite often, but not always) seems to become a  
tradition of our project, which even a log parser should know about :)

WBR,
Aleksey Bragin.

[Dmitry Gorbachev]

One drawback of these schemes is that commit messages cannot be edited
afterward ("what was written by a pen, cannot be taken out with an
axe.")

Maybe it would be better to commit changelog entries into special
files (one per component, to minimize the probability of conflicts, or
per group of components, or even per developer)?

[Zachary Gorden]

What do you mean commit messages can't be edited afterwards?  They can't be
edited right now anyway.  And the current formatting proposals are so that a
script can be used to auto-generate a changelog, which I expect developers
to still look through to determine if there are mistakes.

Z98

[Matthias Kupfer]

Hi folks,

I suggest the following workaround to fix this issue:

- we introduce an additional prefix for a commit message line to mark a 
changelog entry
- the prefix is "[CL]" for a general entry or "[CL:cat1:cat2:cat3]" for an 
hierarchical categorization cat1 -> cat2 -> cat3 aso.
- we limit the changelog to one line - we can generate several entries with 
one commit message (by using multiple changelog lines)

I disagree with xml processing: No semi-XML stufff or more complex operations 
on commit messages..

Request for comments

Matthias
-- 
Matthias Kupfer          phone [phone]
Wilhelm-Firl-Straße 21   mobile [phone]
09122 Chemnitz, Germany

[Colin Finck]

Matthias Kupfer wrote:
> we introduce an additional prefix for a commit message line
>
> to mark a changelog entry

Ok, that's what KJK's suggestion was also about.
> the prefix is "[CL]" for a general entry or
>
> "[CL:cat1:cat2:cat3]" for an 
> hierarchical categorization cat1 -> cat2 -> cat3 aso.

Ok, as long as this hierarchical categorization is just limited to subitems
of .rbuild modules (i.e. [ntoskrnl:io]).
I don't think that modules like [winemine] should get any extra hierarchical
structure, that would only make them too clumsy. Additionally, we can still
decide later, into which top-level categories these modules belong to.
> we limit the changelog to one line - we can generate
>
> several entries with one commit message (by using multiple changelog

lines)

Well, I'd appreciate if something like the following would also be possible:

---------------------------------------------------------------
[winemine] Fixed this.
It had a terrible bug.

[user32] Same thing here.

Arch, what the hell did you do?!
---------------------------------------------------------------

The separator between the changelog entry and the detailed commit
message/Arch bashing would be one empty line then as long as no other prefix
follows.

But well, after all, I don't see many differences from your suggestion to
KJK's one.
And good old ROS philosophy taught us that we should not waste time on long
discussions about minor details, so let's soon agree on a common proposal
and ask for votes from the other developers.

Best regards,

Colin

[Gregor Gullwi]

My two cents:

XML: Too complicated for manual writing

Colin Finck wrote:
> [winemine] Fixed this.
> It had a terrible bug.
>
> [user32] Same thing here.
> Arch, what the hell did you do?!

Personally I liked this approach as it's easy to type.

-Gregor