cairomm has switched to git. I have no need for what git offers, being quite happy with svn, and I’m generally annoyed at having to change the tools I use unnecessarily, but Jonathan Jongsma does most of the cairomm work so he gets to choose. So far I’m learning how to do the basic stuff:
Check it out:
git clone git.cairographics.org:/git/cairomm
Get a diff of my changes:
git commit -a -m “a paste of my changelog entry”
git pull
git diff origin HEAD > my-changes.patch
I know that’s probably not how I’m meant to work with git but I don’t currently want to change how I work. I like to make patches, and it annoys me that even that is so involved. I might use other stuff later, but I’m not going to be forced to do it now.
But I’d really like a git version of the prepare-ChangeLog.pl script, which currently only supports CVS and SVN. Does anyone have one?
Update: MOAP‘s “moap changelog prepare” command does this wonderfully, and supports cvs, svn, and maybe others too. It makes me happy.
Just a ChangeLog and none of your nonsense
I also know that various mad people think that ChangeLogs are unnecessary and/or should just be generated from commit logs. This is silly and doesn’t ever work. I’ve seen it fail again and again. Why don’t your dangerous optimism LEDs flash just at the thought of it?
I’d be just slightly persuaded if anyone could show an http URL of even one ChangeLog in one git project that listed files changed and functions in those files changed, instead of the vagueness that you normally get when you tell people just to say something in a commit message with no review of what they’ve changed or how they are explaining it. Your tool isn’t better than a ChangeLog yet.
Please think before you post examples. Just because you have a URL of a generated ChangeLog, that doesn’t mean that the content is any good. And it’s not enough that I could theoretically write some scripts or click all over a website to see what was changed in what function, which I could theoretically understand without any comments about the changes (don’t get me started about lack of code comments in general). A nice ChangeLog would just explain what was done and get out of my way and I could even read it in the tarball. I’ve been to ClearCase and I’m not going back.
I think the idea is that you write the commit messages as if they were changelog entries (which is what most people do anyway) and stop manually maintaining the ‘ChangeLog’ file itself. When it’s time to release you generate the file from the commits for the benefit of those who don’t track the repository.
As Xán said. If you want to have function granularity in your ChangeLog: include it in your commit messages. Having second-class commit messages is crap, as it leaves anyone actually trying to use the revision control system in the dark.
The main source of opposition to ChangeLogs when you already have a competent RCS isn’t that people can’t be arsed writing them, it’s that it breaks every merge ever. This doesn’t matter with SVN, but it’s crucial with distributed revision control systems.
Xan said:
> think the idea is that you write the commit messages as if they were changelog entries
But nobody does, mostly because that’s too late to be putting your ChangeLog entry together, and too late to be checking your changes by describing them.
Daniels said:
> Having second-class commit messages is crap
I’ve always just pasted the ChangeLog entry when using cvs and svn. That’s far more information than I see in the commit messages for most projects that use git or bzr.
> people can’t be arsed writing them
When I’m the maintainer it doesn’t get committed if people can’t be arsed to maintain quality.
Murray said:
> Xan said:
> > think the idea is that you write the commit messages as if they were changelog entries
> But nobody does, mostly because that’s too late to be putting your ChangeLog entry together, and too
> late to be checking your changes by describing them.
So vi .changes or something, and keep a running notation. Nothing’s stopping you from writing your commit messages as you go; you don’t have to write them all that second.
> Daniels said:
> > Having second-class commit messages is crap
>
> I’ve always just pasted the ChangeLog entry when using cvs and svn. That’s far more information than I > see in the commit messages for most projects that use git or bzr.
Obviously you haven’t looked at the kernel or X too much. :) Most of those don’t describe the function name, admittedly, but that’s because commits became _extremely_ cheap when we moved to git, so we commit early and commit often. If something has four logical components, then it gets four commits (unless they’re all inter-related).
> > people can’t be arsed writing them
>
> When I’m the maintainer it doesn’t get committed if people can’t be arsed to maintain quality.
Sure, but this philosophy apparently stops at the moment you commit.
> Nothing’s stopping you from writing your commit messages as you go
I do this, as I did with cvs and svn. My problem is with projects that encourage people not to detail the changes ever.
> commits became _extremely_ cheap when we moved to git
I imagine that, compared to a ChangeLog, it leaves a lot less actually-readable information. Not writing that information down makes it easy to be lazy, which is nice for developers in isolation but it doesn’t help other people understand what you’ve done.
And I’d really like a URL of an x.org ChangeLog or your equivalent. I already expect to be horrified that it doesn’t mention function names, but I’d like to look.
> > commits became _extremely_ cheap when we moved to git
>
> I imagine that, compared to a ChangeLog, it leaves a lot less actually-readable information. Not writing
> that information down makes it easy to be lazy, which is nice for developers in isolation but it doesn’t help
> other people understand what you’ve done.
You’re utterly misreading what I said by discarding the context (but thanks for the lecture anyway). Commits are cheap, so we do lots of them. Instead of one megacommit across fifty files and god knows how many functions, you break that up into vastly more small commits. ‘Change lots of stuff about timers’ becomes:
‘Timers: CheckExpiry: Loop to top if list changes
If we change the list in CheckExpiry(), go to the top if the list changed, as timers can fall out of the list as a result of this.’
and so on, and so forth.
Working like this has many other good properties wrt git, including git bisect actually being useful (‘now, what in this 50,000 line patch caused things to stop working?’). git without merges and bisect doesn’t seem overly useful to me.
They’re only part of the release tarballs. (And some are, obviously, better than others.)
Well, I am late, but you search something like that?
http://taschenorakel.de/gitweb/?p=scmtools;a=tree;h=master;hb=master
I generally agree with Daniel, but that’s not the point of this comment :) If you want equivalent to prepare-changelog.pl for git, go get Thomas Vander Stichele’s moap (http://thomas.apestaart.org/moap/trac/). The latest version will do this for you. the syntax is a little different (`moap changelog prepare`, which can be shortened to `moap cl prepare`), but it does the same thing.
Well I have created A tool I call “plog” which does a nice job creating changelogs however you want it.
There is an outdated example here: http://grillbar.org/plog/ChangeLog-tracker.html#415
Notice that I can point at specific revisions. Furthermore you will notice that the changelog integrates with bugzilla and Gnomes viewcvs. And ofcourse plog can generate standard txt ChangeLogs as well.
I would like to hear some arguments on why the bog standard ChangeLog with manual copy paste can in *any* way be better than a full html changelog like my example. If you ask me the ChangeLog format is a relic of the past that only sticks around because there is a Nash equilibrium.
For the lastest plog release check out http://www.grillbar.org/wordpress/?p=186. It is by no means end-user friendly yet, but if there is demand I will make it so.
I was going to write about moap, which uses ctags to do the function stuff AFAIR. It is already fairly good replacement for the beloved prepare-ChangeLog.
I would also like to comment about the cheap, step-by-step diff that git helps you to work with: usually, I read the one line description and quickly look at the amount of code changed and where it applies. Then, usually, the patch is rather small, smaller than a typical Gnome SVN patch (coming from bugzilla). It is easy to review it. And second, this small diff touch only a few function, that the commitdiff itself shows you in the top! Its better than a ChangeLog, where you cannot match the change that you read and the commit that produces it (and see the actual change by this mean). at least, it is how I feel.
Changing tools/method is difficult when we are happy about the one we use everyday, nevertheless, the effort is rewarded with git :)
To give a +1 to moap and git over GNOME SVN, there is an ongoing work to make moap work with git-svn. Hence, you can still work with the required ChangeLog but you can use your local repository to make you feature-patch work easier, and in an incremental manner.
Murray, you make me feel I don’t blog enough about moap when I was feeling I already blog too much about it!
I’m glad other people have pointed it out.
As for the usefulness of ChangeLog, come see my talk at GUADEC where I will talk about this topic among others.
http://trac.webkit.org/projects/webkit/browser/trunk/WebKitTools/Scripts/prepare-ChangeLog
cheers
z.
I’m becoming a fan of:
1. Detailed ChangeLog explaining “why”. You can already know “what” from a diff.
2. One-line commit message so that gitk will display it nicely.
I used to use
{cvs,svn} commit -m “`head -42 ChangeLog`”
all the time, but if you do that with git all you get in gitk is a display of
Federico Mena Quintero 2007-01-01
Federico Mena Quintero 2007-01-02
Federico Mena Quintero 2007-02-05
Detailed ChangeLogs are extremely useful, but they don’t make for easy browsing when you just want to know what was done in a few words. My ideal ChangeLog entry looks like this:
Federico Mena Quintero 2007-01-02
Fix http://bugzilla.gnome.org/show_bug.cgi?id=12345 – the frobs are not being glommed.
* file.c (some_func):Glom the frobs; we weren’t calling foo() in the right spot.
* file2.c (foo): Handle the case where the frob is funky.
So, one-liner or short paragraph with a description, and then the actual what/why details.
[And yes, not writing proper ChangeLogs is criminal negligence.]
Daniels,
sorry if I misunderstood you. However, I still think we fundamentally disagree about how much detail is useful in ChangeLogs.
elmarco,
I don’t quite see the point of commits that are smaller than a typical GNOME patch. A patch usually does one thing, with all the changes that are necessary to do that thing, and doesn’t produce any build breakage, so you can understand the change as a whole. I certainly wouldn’t want to see patches in bugzilla broken up into arbitrary parts. Where there are logical separate steps in implementing something very large, I’d already encourage people to break them up.
hi murray,
the small diffs should not break anything! branch&merge is probably so easy and convenient that it replaces any “feature patch” that we commonly found on bugzilla. And it has other advantages.
The thing I just don’t get in these arguments is that why, why would you change the content of the message when the change would be only about its location. I just don’t see how they could possibly be related unless you’re undisciplined to begin with. It’s like saying using Word to write a mail, printing it and sending it by snail mail and then switching to e-mailing instead would somehow change your thoughtful writings into omg lolz kthxbye, or worse.