{"thread":{"id":"23218","subject":"[GSoC Proposal/RFC] Rolling commit message writing","startedAt":"2010-03-28T19:32:02Z","lastAt":"2010-03-30T17:27:25Z","messageCount":7,"participants":["Daniel Thomas","Avery Pennarun","Jonathan Nieder","Ramkumar Ramachandra","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"138033","messageId":"alpine.DEB.1.00.1003281834520.13534@pip.srcf.ucam.org","threadId":"23218","inReplyTo":null,"subject":"[GSoC Proposal/RFC] Rolling commit message writing","fromName":"Daniel Thomas","fromEmail":"drt24@srcf.ucam.org","sentAt":"2010-03-28T19:32:02Z","receivedAt":"2010-03-28T19:32:02Z","isPatch":false,"sender":{"key":"drt24@srcf.ucam.org","avatar":null},"body":"Hello,\n\nI looked at the ideas on the wiki ( \nhttps://git.wiki.kernel.org/index.php/SoC2010Ideas ) and then I remembered \nthat I had an itch to scratch when it came to git.\n\nSo I have written a proposal for something which is not on that list:\nhttps://git.wiki.kernel.org/index.php/User:Drt24/GSoC2010/\n\nThis is included below to allow for easier commenting on it.\n\nSince this proposal is not on the ideas list I am also looking for someone \nto mentor this project.\n\nHowever if it is considered that this is a silly idea (I hope it isn't) \nthen I will write a proposal for the \"Merge helper for LaTeX files\" as \nthis scratches another of my itches.\n\nBegin proposal:\n\n== Project Goals ==\n\n=== What is the goal of your project? ===\nTo make it easier for developers to write good commit messages.\n\n=== What you are going to try to accomplish with your project? ===\nCurrently it is fairly easy to write good commit messages but the effort \nthat this requires of developers can be reduced still further.\n\nThis would be achieved by adding a built in system for working on a commit \nmessage during the stage of adding changes.\n\nCurrently this can be done manually using \"-F , --file=\" in \ngit commit but we can do better than that. Specifically changes to git add \n[--interactive | -i] to add an 'am' or similar command to allow adding a \nfile and then prompting for a message about the changes to that file. Also \nchanges to git add [--patch | -p] to add 'm' and 'c' options to git add \n--patch to allow the addition of a message for the current hunk ('m') and \nto do a commit (prompting for review) before returning to the hunk \ncurrently in focus ('c').\n\n=== How would you measure its success or failure? ===\n* The creation of a good API for editing commit messages for work that is \nin the process of being added for commit.\n* The integration of this API with currently existing CLI tools such as \ngit add so that it fits seamlessly with developer's workflow.\n* The modification of existing documentation to properly reflect this \nchange.\n* The addition of any additional documentation on how to use this new \nfeature.\n* The addition of thorough testing of this feature to 'git.git/t'.\n* Compliance with SubmittingPatches and CodingGuidelines.\n* Work should be undertaken with careful communication with the community.\n\n=== The project in more detail. ===\nA backend for storing the commit message that is being worked on, probably \nusing a file called COMMIT_NEXTMSG in .git/ (following the standard set by \nCOMMIT_EDITMSG). With a file format for describing the commit message, \nthis would be a normal text file but with the use of \n\"/path/to/file.extension:[line number | line-range:] \" to store the various bits of commit message as they \nare added. (alternatively it might be better to use the git notes system \nbut I haven't looked into this yet)\n\nTeaching 'git commit' about this so that it appends the contents of this \nfile to the commit message supplied at the next commit if '-m' is used or \nif [-n | --nextmsg] is used then it just uses the contents of the file (of \ncourse [-e| --edit] would allow this to be subsequently edited.\n\nTeaching 'git commit' --rolling or something similar which would open \nCOMMIT_NEXTMSG in $GIT_EDITOR.\n\nTeaching 'git add [-i | --interactive]' an 'am' or similar command for \n'add and prompt for message' (with care to not spoil the current \ninterface.\n\nTeaching 'git add [-p | --patch]' the 'm' and 'c' commands for adding a \nmessage about the changes in the current hunk and for committing changes \nadded so far after being shown 'git status' being prompted as to whether \nthe user wishes to continue (y/n) where 'y' shows the commit message in \nGIT_EDITOR such that writing from that commits and returns the user to the \nhunk they were looking at and 'n' takes them straight back to the hunk. \nThis makes it easier to separate out multiple atomic changes from a file.\n\n=== Schedule ===\n* 3rd June begin work in earnest: (my last exam is on this day).\n* 9th June finish first version of backend and API.\n* 15th June finish writing tests on backend and API and any changes \nsuggested by the testing or after reveiw.\n* 22nd June finish teaching git commit --rolling\n* 28th June finish teaching git add [-i | --interactive] the 'am' (add \nwith message) command.\n* 9th July finish teaching git add [-p | --patch] the 'm' (add with \nmessage) command.\n* 12th July mid term evaluation\n* 16th July finish teaching git add [-p | --patch] the 'c' (commit with \nedit returning here) command.\n* 26th July finish teaching git commit [-n | --nextmsg] and to use the \nCOMMIT_NEXTMSG if available.\n* 2nd August write lots more tests on everything implemented so far. \nEnsure that all known bugs are properly fixed. Make any changes suggested.\n* 9th August check all the documentation and make all the necessary \nchanges. Write any more additional pieces of documentation necessary e.g. \ntutorials.\n* 9th August suggested pencils down deadline.\n* 16th August firm pencils down deadline, finish rechecking all code, \ndocumentation, tests and submitting patches to the mailing lists. Write \nfinal evaluation.\n* 20th August final evaluation deadline.\n* Continuing: provide any necessary support for these changes and fix any \nbugs that are found subsequently. Continue lurking on the mailing list and \n#git. Help with the continued development of git.\n\n== Interfaces ==\n\n===What parts of Git will you need to call?===\n* editor.c\n* strbuf.c\n* string-list.c\n* git show\n* Those files which I am also modifying, see below.\n\n=== What parts of Git might you need to change? ===\n* git-add--interactive.perl\n* commit.c\n* builtin/{add.c,commit.c}\n* Documentation/{git-commit.txt,git-add.txt}\n* t/{t750?-commit*,t370?-add*} (probably just adding new files)\n\n== About You ==\n\n=== Projects that I have worked on ===\n\nLast term I worked on the quebec project for my group project which is \npart of my University course. This can be seen here: \nhttps://www.srcf.ucam.org/quebec/tomcat/quebec/ and the code is here: \nhttps://www.srcf.ucam.org/quebec/quebec-0.1.tar.gz though it is not really \nin a fit state for use by anyone else and we never got around to talking \nabout licenses. I wrote the User Management system, and ran the server \n(tomcat), version control (SVN after a vote by the group which had in \ngeneral not used VCSs before) and unit testing (junit4). I also rewrote \npart of the comms system and wrote a test client for it. This project was \nalso in Java. We did a lot of communication in person but we also used \nGoogle wave and Google docs. There were five developers in my group and we \nhad a client from IBM.\n\nLast summer (2009) I worked on the second iteration of the \nReadYourMeter.org project (which is still in development) I wrote 8.7ksloc \nof Java and GWT. This code is available under the GPL v2 but since we \nhaven't done a release yet it isn't linked to from anywhere. I was the \nonly developer on this project, I communicated with my supervisor both in \nperson and via email.\n\nIn Christmas 2008 I wrote a simple command line \n[https://www.srcf.ucam.org/~drt24/blog/2008/12/10-release-of-fractals/ \nfractal image generator] in SML for my own amusement.\n\nIn February 2007 I contributed a couple of minor patches to the \nWorldforge.org project (in python). Most communication was done on #lounge \non irc.worldforge.org, but I also used the mailing list (particularly for \nthe submission of patches). I had CVS commit rights but they have \nsubsequently moved to Git and I have only been lurking on their mailing \nlist since the summer of 2007.\n\n[https://www.srcf.ucam.org/~drt24/onlineCVdrt24.pdf My CV.]\n\n===Do you have any prior Git experience? Have you started to get \ninvolved?===\n\nI have been using Git for over a year for various personal projects \nranging from academic work and projects to websites I have worked on for \nvarious people. I haven't used it in a multi-user manner as in general it \nhas been just me working on these projects in git.\nI have pulled git.git and successfully compiled and installed it (which \nwas pleasantly easy), I also ran the tests in git.git/t which seemed to go \nas well as it was supposed to.\n\nI have been lurking on #git for a few days now and I have tried to provide \nsupport where I could for those questions which were asked when I was \nwatching. I have joined the git mailing list and while I haven't been \nreading all the emails I have been reading a selection of them.\n\nIf accepted I would send a weekly progress report to the mailing list \n(unless people would object to that). I would ensure that I regularly \npushed my changes to somewhere public so that anyone interested could look \nat them. I would ensure that I listened to advice given to me and acted \nupon it. I would start submitting patches to the mailing list as \n[PATCH/RFC] once I have finished a section of work to allow anyone to make \nsuggestions on how to do it better early on in the project. I would also \nremain on #git and increase the proportion of mailing list emails which I \nread.\n\n=== Prior contact with the Git community ===\n\nI talked to \n[http://colabti.org/irclogger/irclogger_log/git?date=2010-03-23#l2369 \n'Paradox' and 'charon' about this on #git] after 'Paradox' had asked if \nsomething similar was available. 'charon' mentioned that git commit \n--append --only or 'git rebase --interactiv\n\nI posted a link to this proposal on #git a few hours before I posted it \nhere but there were no responses to it.\n\n--\nThank you,\n\nDaniel\n"},{"id":"138128","messageId":"32541b131003291331y3ae5ca23la33466d588c1b9e1@mail.gmail.com","threadId":"23218","inReplyTo":"alpine.DEB.1.00.1003281834520.13534@pip.srcf.ucam.org","subject":"Re: [GSoC Proposal/RFC] Rolling commit message writing","fromName":"Avery Pennarun","fromEmail":"apenwarr@gmail.com","sentAt":"2010-03-29T20:31:00Z","receivedAt":"2010-03-29T20:31:00Z","isPatch":false,"sender":{"key":"apenwarr@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20592?v=4"},"body":"On Sun, Mar 28, 2010 at 3:32 PM, Daniel Thomas wrote:\n> Currently it is fairly easy to write good commit messages but the effort\n> that this requires of developers can be reduced still further.\n>\n> This would be achieved by adding a built in system for working on a commit\n> message during the stage of adding changes.\n>\n> Currently this can be done manually using \"-F , --file=\" in git\n> commit but we can do better than that. Specifically changes to git add\n> [--interactive | -i] to add an 'am' or similar command to allow adding a\n> file and then prompting for a message about the changes to that file. Also\n> changes to git add [--patch | -p] to add 'm' and 'c' options to git add\n> --patch to allow the addition of a message for the current hunk ('m') and to\n> do a commit (prompting for review) before returning to the hunk currently in\n> focus ('c').\n\nThe extra prompting seems to me like it would slow down the process of\n'git add -p' by making it take too many steps. Normally when I create\na commit, I like to think of \"which lines will I commit?\" and \"what is\nthe description of the whole commit?\" as separate questions, whereas\nthis workflow would interweave the two and confuse me.\n\nDo other people prefer it that way?\n\nSecondly, I'm concerned that if you can't remember the description of\nyour entire commit by the time you commit it, then your commit is too\nbig. The usual solution is to create multiple, smaller commits that\nare easy to describe. If at the end you find yourself with too many\ncommits, you can always join them together with git rebase.\n\nYou might also like 'git commit -v', which shows the actual diff to be\ncommitted as part of your default commit message. Then you can write\nyour message while looking at it, making it easy to describe exactly\nwhat you changed.\n\nGiven these existing capabilities, is it still worth adding the\nfeature you propose?\n\nHave fun,\n\nAvery\n"},{"id":"138152","messageId":"20100330030508.GA2887@progeny.tock","threadId":"23218","inReplyTo":"32541b131003291331y3ae5ca23la33466d588c1b9e1@mail.gmail.com","subject":"Re: [GSoC Proposal/RFC] Rolling commit message writing","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-03-30T03:05:08Z","receivedAt":"2010-03-30T03:05:08Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nAvery Pennarun wrote:\n\n> Given these existing capabilities, is it still worth adding the\n> feature you propose?\n\nI think it might be, in some modified form.\n\nSuppose I am working on a medium-sized change that for reasons of\nbisectability or ontology has to be one commit. In the middle of\nworking, I notice I needed to do something nonobvious. Currently when\nthis happens, I get out a pad of paper and write it down, so I can be\nsure to mention it in the commit message.\n\nWouldn’t it be nicer in such situations to be able to say git add\n--commit-message or similar, open an editor, and write the note right\naway?\n\nIn other words, it would be nice to have a file in .git that is\n\n - cleared on successful commit\n - automatically used to fill COMMIT_EDITMSG, like MERGE_MSG is\n\nI suspect something like this can be achieved by the combination of\nthe commit.template configuration variable and a post-commit hook to\nclear the file, but I haven’t tried it.\n\nRegards,\nJonathan\n"},{"id":"138156","messageId":"32541b131003292132q10db3c5eh1bb6443d625fcb82@mail.gmail.com","threadId":"23218","inReplyTo":"20100330030508.GA2887@progeny.tock","subject":"Re: [GSoC Proposal/RFC] Rolling commit message writing","fromName":"Avery Pennarun","fromEmail":"apenwarr@gmail.com","sentAt":"2010-03-30T04:32:11Z","receivedAt":"2010-03-30T04:32:11Z","isPatch":false,"sender":{"key":"apenwarr@gmail.com","avatar":"https://avatars.githubusercontent.com/u/20592?v=4"},"body":"On Mon, Mar 29, 2010 at 11:05 PM, Jonathan Nieder wrote:\n> Avery Pennarun wrote:\n>> Given these existing capabilities, is it still worth adding the\n>> feature you propose?\n>\n> I think it might be, in some modified form.\n>\n> Suppose I am working on a medium-sized change that for reasons of\n> bisectability or ontology has to be one commit.  In the middle of\n> working, I notice I needed to do something nonobvious.  Currently when\n> this happens, I get out a pad of paper and write it down, so I can be\n> sure to mention it in the commit message.\n\nWhen I have this situation, I generally just make a temporary commit\nwith \"git commit\", then revise it using \"git commit --amend\" over\ntime.\n\nOr else I make a series of commits, then *later* squash them all\ntogether using 'git merge --squash' or 'git rebase -i'.\n\nIt seems like the suggested feature would encourage people to do it\nthe \"wrong\" way (not creating temporary commits, thus making it easy\nto make a mistake and blow things away) just because they aren't aware\nof the above options.\n\nIs there a reason that these methods don't work for you?\n\nThanks,\n\nAvery\n"},{"id":"138158","messageId":"20100330045704.GA9004@progeny.tock","threadId":"23218","inReplyTo":"32541b131003292132q10db3c5eh1bb6443d625fcb82@mail.gmail.com","subject":"the careless committer and fear of commitment (rebase -i vs add -p)","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-03-30T05:02:48Z","receivedAt":"2010-03-30T05:02:48Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Avery Pennarun wrote:\n\n> I generally just make a temporary commit\n> with \"git commit\", then revise it using \"git commit --amend\" over\n> time.\n> \n> Or else I make a series of commits, then *later* squash them all\n> together using 'git merge --squash' or 'git rebase -i'.\n> \n> It seems like the suggested feature would encourage people to do it\n> the \"wrong\" way (not creating temporary commits, thus making it easy\n> to make a mistake and blow things away) just because they aren't aware\n> of the above options.\n> \n> Is there a reason that these methods don't work for you?\n\nI like ‘git diff --cached’ and ‘git diff’ to show the entire list\nof staged and unstaged changes. I don’t consider this “wrong” at all.\nGenerally, once something becomes precious enough to be worth keeping,\nit is already in presentable form and I can come up with an appropriate\ncommit message. I understand that other people work differently; this\nis just my personal preference.\n\nI also use the stash heavily, which maybe mitigates the “content could\nbe blown away with a simple rm -f” problem.\n\nYou might also be interested in Pasky’s analysis at\nhttp://thread.gmane.org/gmane.comp.version-control.git/138641/focus=138672\n\nCheers,\nJonathan\n"},{"id":"138162","messageId":"f3271551003292314v23058945vb432cc4c8a601aca@mail.gmail.com","threadId":"23218","inReplyTo":"20100330045704.GA9004@progeny.tock","subject":"Re: the careless committer and fear of commitment (rebase -i vs add -p)","fromName":"Ramkumar Ramachandra","fromEmail":"artagnon@gmail.com","sentAt":"2010-03-30T06:14:01Z","receivedAt":"2010-03-30T06:14:01Z","isPatch":false,"sender":{"key":"r@artagnon.com","avatar":"https://avatars.githubusercontent.com/u/37226?v=4"},"body":"Hi,\n\nOn Tue, Mar 30, 2010 at 10:32 AM, Jonathan Nieder wrote:\n> I like ‘git diff --cached’ and ‘git diff’ to show the entire list\n> of staged and unstaged changes.  I don’t consider this “wrong” at all.\n\nOn a related note, my workflow is somewhat similar: I just use Magit\nwithin Emacs, which essentially does the same thing. The staging area\nin Git really helps me organize my work, and I wouldn't mind attaching\na small note to it that I can refer to while writing my commit message\n(much like Jonathan's idea). However, I don't think this task is large\nenough for an entire GSoC.\n\nAlso, I'm positively opposed to the idea of a complex interactive\ncommand-line interface. If someone *did* want that kind of complexity/\ninteractivity, they ought to use something like Magit: a cli can't\neven come close.\n\n-- Ram\n"},{"id":"138194","messageId":"20100330172725.GF17763@coredump.intra.peff.net","threadId":"23218","inReplyTo":"32541b131003291331y3ae5ca23la33466d588c1b9e1@mail.gmail.com","subject":"Re: [GSoC Proposal/RFC] Rolling commit message writing","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-03-30T17:27:25Z","receivedAt":"2010-03-30T17:27:25Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Mar 29, 2010 at 04:31:00PM -0400, Avery Pennarun wrote:\n\n> Secondly, I'm concerned that if you can't remember the description of\n> your entire commit by the time you commit it, then your commit is too\n> big. The usual solution is to create multiple, smaller commits that\n> are easy to describe. If at the end you find yourself with too many\n> commits, you can always join them together with git rebase.\n\nThat was my first thought, too. I like your suggestion elsewhere in the\nthread of making many small commits, and then squashing them later if\nyou like.\n\nStill, I can see how people might prefer to use this as part of their\nworkflow, so I am not against the feature itself.\n\nHowever, I am really concerned with it as a GSoC project. It just\ndoesn't seem like a big enough feature to take the whole summer. In the\nschedule, there is a week of implementing \"git add -p\n--add-with-message\". It seems like that should be hours, not days.\n\nI wonder if it could be rolled into a more comprehensive proposal\nconcerning commit workflows (though I admit, I don't personally have any\nother ideas in the area).\n\n-Peff\n\nPS Daniel (and other potential GSoC'ers who are reading), please don't\ntake this as discouragement of presenting proposals that aren't on the\nideas wiki. I really really like the concept of somebody working on\ntheir own itch, as I think they tend to have a clearer idea of what the\nsolution should look like. I'm just concerned this particular proposal\nisn't big enough.\n"}]}