Not logged inOpenClonk Forum
Up Topic Development / Developer's Corner / Commit messages
- - By Günther [de] Date 2009-05-09 15:09
I'd suggest we use the semi standard format: One line summary, with longer explanation separated by two newlines below. We might also want to use some common prefixes for the summary to see at a glance which is being modified. Something like docs:, engine:, game:, etc. Unfortunately, it's not easy to modify the commit message with mercurial, so we'll likely still see substandard messages, which limits their usefulnes for automatically generated changelogs. The question is whether we still want those, or whether we can point people at a webpage of the repository and write some "player oriented" changelogs for every release. I'd favor the latter.
Reply
Parent - - By Newton [es] Date 2009-05-09 19:01
Best you post a full example here how it should look with prefixes, explanation etc.

I agree with separate changelogs for players/release and developers/repos
Parent - By Günther [de] Date 2009-05-09 20:28
For examples see my commit messages ;-)

This one lacked a prefix originally, but should probably have been this:

Engine: Remove most shareware restrictions

One can now start the developer mode and every scenario without
a registration, but the game still complains about not being registered.


Prefixes I have used include Linux and X11.
Reply
Parent - - By PeterW [de] Date 2009-05-10 20:59
How about the classic annotations detailing the nature of a change? Makes it easier to generate those handy change lists.
Parent - - By Günther [de] Date 2009-05-10 21:50
Do you have any use case for the change lists that wouldn't be better served by the full commit history? I never read changelogs when I can get the version control information instead. The only thing that comes to mind would be a scripter wanting to know what's new in C4Script, but I still think that we should give them real documentation instead of an uninformative oneliner. If we can't, an automatic listing of every engine function with argument types would be more helpful than those old changelogs.
Reply
Parent - - By PeterW [de] Date 2009-05-16 17:36
The full change list is way too verbose and typically littered with totally uninteresting stuff like "some more .hgignores", "oops, fixed some minor typos" or "made PeterWs evil changes compile properly on GCC" or whatever. I actually often look at the parsed change log for reference.

And you really don't want scripters to have to scan the documentation for changes every time. I remember that from CP times and didn't like it one bit. Besides, the documentation always lags way behind - and I doubt that will change just like that.
Parent - By Günther [de] Date 2009-05-16 18:23

> And you really don't want scripters to have to scan the documentation for changes every time


That's why the documentation has "Functions by Version". And the documentation not being up to date is one of the things I want to fix. We need to consider wether it needs to be easier to update the documentation, or if it would be better to just disallow pushing changes that lack documentation updates. With a distributed version control system, those changes could be pushed to a separate repository for review first.

> I actually often look at the parsed change log for reference.


To answer which questions? I find history digging with gitk much more useful and reliable, and the "DataMining" window from TortoiseHG is probably also superior. And it would get even better if the changelog did not only consist of one terse line barely describing what changed, but also included the rationale for the changes.
Reply
Up Topic Development / Developer's Corner / Commit messages

Powered by mwForum 2.29.7 © 1999-2015 Markus Wichitill