{"thread":{"id":"14295","subject":"Git, merging, and News/Relnotes files","startedAt":"2008-07-05T07:24:13Z","lastAt":"2008-07-09T01:14:28Z","messageCount":6,"participants":["Edward Z. Yang","Linus Torvalds","Dmitry Potapov"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"82273","messageId":"g4n7j6$359$1@ger.gmane.org","threadId":"14295","inReplyTo":null,"subject":"Git, merging, and News/Relnotes files","fromName":"Edward Z. Yang","fromEmail":"edwardzyang@thewritingpot.com","sentAt":"2008-07-05T07:24:13Z","receivedAt":"2008-07-05T07:24:13Z","isPatch":false,"sender":{"key":"edwardzyang@thewritingpot.com","avatar":"https://gravatar.com/avatar/a805a0a3c1d7d36e7fe22270596e4d812723652933c59cac267e67c79126fdd0?d=mp&s=160"},"body":"As a policy on a project that I manage, almost every commit warrants a\nchange to our NEWS (changelog) file, which end-users can browse to get\nan in-depth idea of the changes that have happened from the last\nrelease. If it's an added feature, the changelog includes a description\nof how to use it; if it's a fixed bug, it briefly describes what\nhappened. Internal changes may or may not get added, depending on the\nvisibility of the APIs affected.\n\nSomething that I've noticed recently, as we've started migrating away\nfrom the ghetto SVN development model to the Git branchy model, is that\nthis NEWS file ends up being the source of a lot of conflicts. Granted,\nthey're easy conflicts to resolve, but still, they make a pull a little\nmore complicated than it should be.\n\nWhat would you guys, as experienced Git users, recommend in this case?\nScrapping a NEWS file and simply drawing up the release-notes shortly\nbefore release (as the Git project does)? Aggregating the Git commit\nmessages into one monster release log? Having the release manager add\nthe NEWS entries himself, and mandate that no patch have it in them?\n\nThanks!\n"},{"id":"82296","messageId":"alpine.LFD.1.10.0807051119170.2815@woody.linux-foundation.org","threadId":"14295","inReplyTo":"g4n7j6$359$1@ger.gmane.org","subject":"Re: Git, merging, and News/Relnotes files","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2008-07-05T18:38:25Z","receivedAt":"2008-07-05T18:38:25Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sat, 5 Jul 2008, Edward Z. Yang wrote:\n> \n> Something that I've noticed recently, as we've started migrating away\n> from the ghetto SVN development model to the Git branchy model, is that\n> this NEWS file ends up being the source of a lot of conflicts. Granted,\n> they're easy conflicts to resolve, but still, they make a pull a little\n> more complicated than it should be.\n\nI don't think anybody really _uses_ the functionality, but git does have \nthe capability to specify special merge drivers based on filenames.\n\nSo you can\n\n (a) create a merge strategy that automaticaly does what you want. There's \n     a built-in driver called \"union\" that may or may not work for your \n     use case.\n\n     See \"Defining a custom merge driver\" in \"man gitattributes\" for more \n     details about this.\n\n (b) Say which files you want to merge with this driver, by having \n     something like\n\n\tNEWS merge=news-merge\n\n     in your .gitattributes file (or in \".git/info/attributes\", if you \n     want to keep this all private to your own setup rather than in a \n     committed file that gets distributed to everybody else too).\n\nand now your NEWS file will be merged using your special \"news-merge\" \ncustom merge function.\n\nOf course, the custom merge driver is only done for non-trivial merges. \nGit will do all the trivial fast-forward merges on its own, and only call \nthe custom merge driver for things that have actual possible data \nconflicts (ie changes in both branches).\n\nNOTE! Keeping an ordered list (like a ChangeLog or a NEWS file) is \nfundamentally not an easy thing to do in a distributed environment. The \n\"union\" merge strategy may well work for you (and if it does, this is all \ngoing to be very easy), but it's also entirely possible that you will find \nthat the ordering in a distributed environment is so unspecified, you'll \nprefer to do the merges by hand _anyway_ in the end.\n\nSo the first thing you should do is probably to just *try* adding that\n\n\tNEWS merge=union\n\nline to your .gitattributes file, and see if it works for you. My personal \nguess is that you'll realize that you really prefer doing the trivial \nmerges manually after all, but hey, maybe not. And as mentioned, you *can* \ncreate your very own merge strategy that knows about the particular rules \nof the files in question, but that gets more complex.\n\nFor example, the default 'union' merge will literally _duplicate_ \nidentical that were added in both branches. So if you cherry-pick a commit \nso that it exists both in the branch you are merging _and_ the branch you \nare merging into, then any additions to the NEWS file will basically show \nup twice, and yet auto-merge \"cleanly\".\n\nWhich is very understandable, but is almost certainly not what you want.\n\n\t\t\tLinus\n"},{"id":"82297","messageId":"486FC65C.70602@thewritingpot.com","threadId":"14295","inReplyTo":"alpine.LFD.1.10.0807051119170.2815@woody.linux-foundation.org","subject":"Re: Git, merging, and News/Relnotes files","fromName":"Edward Z. Yang","fromEmail":"edwardzyang@thewritingpot.com","sentAt":"2008-07-05T19:07:08Z","receivedAt":"2008-07-05T19:07:08Z","isPatch":false,"sender":{"key":"edwardzyang@thewritingpot.com","avatar":"https://gravatar.com/avatar/a805a0a3c1d7d36e7fe22270596e4d812723652933c59cac267e67c79126fdd0?d=mp&s=160"},"body":"Linus Torvalds wrote:\n> So the first thing you should do is probably to just *try* adding that\n> \n> \tNEWS merge=union\n> \n> line to your .gitattributes file, and see if it works for you.\n\nSounds like a good first-step. It's very unlikely that we're going to\nbother writing our own merge strategy for the NEWS file, so if union\nends up being more trouble than its worth, we'll probably end sticking\nwith manual merges.\n\nPieter also suggested (for some reason, I don't see the post on this\nlist) the git-merge-changelog driver from Gnu Savannah. Unfortunately,\nthe log format is a little different from ours (entries are sorted into\nBC-incompatible, features, bugfixes and internal changes), so the driver\nmay not work (it's still worth a try, I imagine).\n\nI'm slightly surprised no one suggested that I can the file, given that\nboth Git and the Linux kernel don't have one.\n\n> For example, the default 'union' merge will literally _duplicate_ \n> identical that were added in both branches. So if you cherry-pick a commit \n> so that it exists both in the branch you are merging _and_ the branch you \n> are merging into, then any additions to the NEWS file will basically show \n> up twice, and yet auto-merge \"cleanly\".\n\nI suppose that's why we have git reset --hard HEAD~. :-) I will\ncertainly keep this gotcha in mind.\n"},{"id":"82298","messageId":"alpine.LFD.1.10.0807051253000.2815@woody.linux-foundation.org","threadId":"14295","inReplyTo":"486FC65C.70602@thewritingpot.com","subject":"Re: Git, merging, and News/Relnotes files","fromName":"Linus Torvalds","fromEmail":"torvalds@linux-foundation.org","sentAt":"2008-07-05T20:03:00Z","receivedAt":"2008-07-05T20:03:00Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sat, 5 Jul 2008, Edward Z. Yang wrote:\n> \n> I'm slightly surprised no one suggested that I can the file, given that\n> both Git and the Linux kernel don't have one.\n\nWell, I personally think ChangeLog files are a total waste of time. You're \nmuch better off autogenerating those from the real logs, I think.\n\n[ Although in all honesty, I also think we could improve on our reporting \n  tools, and have ways to perhaps highlight big or important changes some \n  way ]\n\nBut a NEWS file that actually talks about new features is a different \nthing. It can make lots of sense to maintain something like that, so I \nwouldn't suggest canning it if it works for you. I'm not convinced it \nwould work for the kernel, but I suspect it can work really well for other \nprojects.\n\n> > For example, the default 'union' merge will literally _duplicate_ \n> > identical that were added in both branches. So if you cherry-pick a commit \n> > so that it exists both in the branch you are merging _and_ the branch you \n> > are merging into, then any additions to the NEWS file will basically show \n> > up twice, and yet auto-merge \"cleanly\".\n> \n> I suppose that's why we have git reset --hard HEAD~. :-) I will\n> certainly keep this gotcha in mind.\n\nWell, the real problem with a clean automatic merge is not that it can't \nbe undone (or better yet - fixed: just edit the NEWS file and then do a \n\"git commit --amend NEWS\" to fix up the atomatic merge), but the fact that \nmost of the time you'll simply never even notice.\n\nIOW, when something merges cleanly (and the 'union' merge will basically \nalways do so), the most common case is probably that people won't even \n_look_ at the end result - especially if it works fine most of the time. \n\nThat's why a trivial conflict can often be better than a silently clean \nmerge: at least it forces people to spend a small amount of brainpower to \nlook at the obvious fix.\n\nBut hey, give it a try. Maybe you'll like the union merge, together with \noccasional manual fixups. Or maybe you'll decide that a specialized merge \nstrategy isn't that painful after all (or can find somebody who already \nwent through the pain and wrote one you can use).\n\n\t\tLinus\n"},{"id":"82372","messageId":"37fcd2780807060753h26d9391crff5f9ba5531db654@mail.gmail.com","threadId":"14295","inReplyTo":"g4n7j6$359$1@ger.gmane.org","subject":"Re: Git, merging, and News/Relnotes files","fromName":"Dmitry Potapov","fromEmail":"dpotapov@gmail.com","sentAt":"2008-07-06T14:53:42Z","receivedAt":"2008-07-06T14:53:42Z","isPatch":false,"sender":{"key":"dpotapov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6568595?v=4"},"body":"On Sat, Jul 5, 2008 at 11:24 AM, Edward Z. Yang\n<edwardzyang@thewritingpot.com> wrote:\n> As a policy on a project that I manage, almost every commit warrants a\n> change to our NEWS (changelog) file, which end-users can browse to get\n> an in-depth idea of the changes that have happened from the last\n> release. If it's an added feature, the changelog includes a description\n> of how to use it; if it's a fixed bug, it briefly describes what\n> happened. Internal changes may or may not get added, depending on the\n> visibility of the APIs affected.\n\nI believe it is better to put all this information directly to the commit\nmessage using some special tagging, so you can extract it automatically\nat the release time and generate the changelog file for users. You may\nedit the generated changelog and commit it directly before release.\n\nHaving one file changed on almost every commit is not a good idea, and\nnot only because it will cause unnecessary conflicts but also it may\nconsiderable increase the size of the whole repository. By default, the\ndelta compression has limit 50, which means that every 50 change of file\nwill become its full copy. If the changelog file is changed very often\nand it is long, it may turn out that changelog alone takes as much space\nas the rest of the source tree.\n\nDmitry\n"},{"id":"82662","messageId":"487410F4.1050808@thewritingpot.com","threadId":"14295","inReplyTo":"37fcd2780807060753h26d9391crff5f9ba5531db654@mail.gmail.com","subject":"Re: Git, merging, and News/Relnotes files","fromName":"Edward Z. Yang","fromEmail":"edwardzyang@thewritingpot.com","sentAt":"2008-07-09T01:14:28Z","receivedAt":"2008-07-09T01:14:28Z","isPatch":false,"sender":{"key":"edwardzyang@thewritingpot.com","avatar":"https://gravatar.com/avatar/a805a0a3c1d7d36e7fe22270596e4d812723652933c59cac267e67c79126fdd0?d=mp&s=160"},"body":"Dmitry Potapov wrote:\n> Having one file changed on almost every commit is not a good idea, and\n> not only because it will cause unnecessary conflicts but also it may\n> considerable increase the size of the whole repository. By default, the\n> delta compression has limit 50, which means that every 50 change of file\n> will become its full copy. If the changelog file is changed very often\n> and it is long, it may turn out that changelog alone takes as much space\n> as the rest of the source tree.\n\nThat is certainly a good technical point, and I will certainly look into\nbuilding a log parser after we wrap up our next release cycle.\n\nP.S. Linus, we ended up manually merging the NEWS file; in some cases\nthere were branch specific changes in the file which would have been\ncompletely inappropriate with a union merge. Thank you for the\nsuggestion, however.\n"}]}