![[de]](/mwf/flags/de.png "Germany")
Writing good commit messages is work, but I'd propose that we adopt some minimal quality standards to make the log easier to read, and improve the chances that a commit message helps somebody a few months or years from now in understanding the commit.Ideally, a message consists of a short summary which helps with finding a particular commit and a longer explanation which explains why somebody bothered doing the commit. Often, the commit message is the only explanation for a particular line of code that will be available later. Obviously, a lot of short commits are self-explanatory, because they fix an apparent bug, but a lot of short commits change something that reasonable people can have different opinions on. And longer commits almost always have a complex reason. I'd like to encourage everyone to supply the reason for the commit after the initial summary line.
I also propose that we start labeling every commit with a short area indicator followed by a colon (:). I prefix commits changing the script engine with Script:, and there are multiple commits which have a scenario name at the beginning. Also established are the names of the operating systems for changes only affecting a particular platform. If a particular commit doesn't have an apparent specific area, I propose we start using Engine:, Game: (or perhaps Planet: for nostalgia's sake?), Docs:, Masterserver:, Installer: or CMake: depending on which directory has the main changes. If the commit touches only one of the other files in the top level, that filename can be used. I think this will make writing immediately obvious commit messages easier. If a commit message is obvious without this, we can keep skipping a prefix, but that requires judgement to determine, which is work.
I think the prefix is useless, because you can achieve the same just by looking at which files were changed. If e.g. you want to check whether there were engine changes after you last compiled, you would list all changes in the source directory.
![[gb]](/mwf/flags/gb.png "United Kingdom")
Well, speaking as someone that is using the revision RSS feed to keep a rough overview of what's happening, having to look at the file list wouldn't really be that convenient. Not sure this is worth having a big discussion over, but I guess I'll prefix my commits in future.
Well, at least when we want to have changelogs for (only) players some kind of prefix come in handy.I mean: A random player would probably not want to know that Sven just fixed OpenGL drawing for new contexts and stuff like that ;)
(aka "Make prefix for players or add signs to differ in the relevance for the player")
![[pl]](/mwf/flags/pl.png "Poland")
Since I like to look at it, I'd like to suggest some tags like [fix] [add] [change] [remove], perhaps colored.
Also, that area indicator idea is very good imho.
It'd be good to see something like [add] Script:new function - xyz(a,b,c), returns a*b/(c+100).
Anyway! I like that idea.
Also, that area indicator idea is very good imho.
It'd be good to see something like [add] Script:new function - xyz(a,b,c), returns a*b/(c+100).
Anyway! I like that idea.
I like your suggestion to have a commit title in the first line and then explain it in the following lines. I'll try to adhere to that.
http://who-t.blogspot.com/2009/12/on-commit-messages.html has a nice description of good commit messages. Some of the guidelines demand a bit more effort than is probably necessary for a mere game, but the direction is sound.
I noticed Newton (?) marked the commit messages for the changelog manually now: http://blog.openclonk.org/2010/12/changes-in-version-1-1-3/ / http://www.ccan.de/cgi-bin/ccan/ccan-view.pl?a=view&i=5925..should we maybe start doing that in the changelog then?
For what purpose? And even if it had any purpose, the categorization is mostly arbitrary anyway: "script: FindConstructionSite return 0 when the search fails" could just as well be labeled bugfix, "update XPM icon from CZ to OC" can be any of bugfix (used the wrong icon before), new feature (shiny new icon for X11 users!) or change. The only thing that's halfway clear is "-": Use it if the commit message uses "remove".What we _could_ do is do the labeling and only pick those changes labeled bugfix for the stable branch. But that wasn't very popular when I last suggested that.
>For what purpose?
Just so that Newton (or someone else) does not have to do it manually every time.
I put together a list of changes manually for the same reason we have a blog at all. Make news about the development of OC more accessible to people who are only marginally involved. What I marked as what (!*+-) doesn't really matter, it would only help to get a rough overview whether this is more of a bugfix release or not. I could also omit them in the future.
Well, as a player I would want answers to these questions:"Is the update big enough to make the game excitingly new again?"
"Which scenarios can I play to see the changes?"
"Which scenarios should I play because they are now better or new?"
"Is the bug that annoyed me gone?"
These can all be answered by a changelog, but do not need to be. The second and third questions are probably worth answering directly. The first one probably only in the negative ("this is a minor bugfix release"), as we of course always think that the game is exciting ;-) I'm not sure whether the last one is worth spending effort on, as it's very subjective. A simple link to the log or shortlog of the repository web interface would also give more of a "look behind the scenes".
I probably should have told you about the draft blog entry I wrote. It would have needed some completion by someone knowing whether other scnearios were notably updated and was obviously written before the windows update problem was noticed.
Anyway, thanks for working on this.
>I probably should have told you about the draft blog entry I wrote. It would have needed some completion by someone knowing whether other scnearios were notably updated and was obviously written before the windows update problem was noticed.
Oops, didn't notice it.
Powered by mwForum 2.29.7 © 1999-2015 Markus Wichitill
