{"thread":{"id":"23262","subject":"Re: [GSoC Proposal/RFC] Rolling commit message writing","startedAt":"2010-03-30T22:34:37Z","lastAt":"2010-03-30T22:34:37Z","messageCount":1,"participants":["Daniel Thomas"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"138226","messageId":"1269988477.17964.49.camel@dell-desktop.example.com","threadId":"23262","inReplyTo":null,"subject":"Re: [GSoC Proposal/RFC] Rolling commit message writing","fromName":"Daniel Thomas","fromEmail":"drt24@cam.ac.uk","sentAt":"2010-03-30T22:34:37Z","receivedAt":"2010-03-30T22:34:37Z","isPatch":false,"sender":{"key":"drt24@cam.ac.uk","avatar":null},"body":"Hello,\n\nI reworked my proposal a bit before submitting it based on feedback I\ngot in #git. The version I submitted is included at the end. First I\nwill try and address the points raised.\n\n        On Sun, Mar 28, 2010 at 3:32 PM, Daniel Thomas <drt24@srcf.ucam.org> 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>, --file=<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        \n        The 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\n        a commit, I like to think of \"which lines will I commit?\" and \"what is\n        the description of the whole commit?\" as separate questions, whereas\n        this workflow would interweave the two and confuse me.\n\nThis would only optionally interleave the two as this would be adding\nnew options and not changing old ones.\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        \nYes however if each commit is endeavouring to ensure that it takes the\nsource tree from one consistent state to another then occasionally\ncommits have to be slightly larger. Of course a series of small\ninconsistent commits can be made and then git rebase can be used to\nstick them together and to write a new commit message. This would offer\nanother method of doing it which would hopefully be useful in some cases\nsuch as when as Jonathan Nieder mentioned the user wants \"I like ‘git\ndiff --cached’ and ‘git diff’ to show the entire list of staged and\nunstaged changes.\". However I can see how it could be considered wrong\nto not commit early and often and that my desire for atomic commits\ncould be a hangover from older VCSs.\n        \n        You might also like 'git commit -v', which shows the actual diff to be\n        committed as part of your default commit message.  Then you can write\n        your message while looking at it, making it easy to describe exactly\n        what you changed.\n\nThough useful, this doesn't work so well when the diff is larger as\nlooking at the diff while writing the commit would result in a lot of\nscrolling.\n\n        Given these existing capabilities, is it still worth adding the\n        feature you propose?\n        \nI would hope that it is, however see below.\n                \n        On Tue, Mar 30, 2010 at 10:32 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:\n        > I like ‘git diff --cached’ and ‘git diff’ to show the entire\n        list\n        > of staged and unstaged changes.  I don’t consider this “wrong”\n        at all.\n        \n        On a related note, my workflow is somewhat similar: I just use\n        Magit\n        within Emacs, which essentially does the same thing. The staging\n        area in Git really helps me organize my work, and I wouldn't\n        mind attaching a small note to it that I can refer to while\n        writing my commit message (much like Jonathan's idea). However,\n        I don't think this task is large enough for an entire GSoC.\n        \nAhh.\n        \n        Also, I'm positively opposed to the idea of a complex\n        interactive\n        command-line interface. If someone *did* want that kind of\n        complexity/interactivity, they ought to use something like\n        Magit: a cli can't even come close.\n        \nI changed the focus in my revised proposal so that the cli interfaces\nare emphasised less with the focus being on the backend for storing and\nmodifying the in progress commit message. The CLIs just test the API and\nprovide mechanisms which some people might find useful.\n\nOn Tue, 2010-03-30 at 13:27 -0400, Jeff King wrote: \n> However, I am really concerned with it as a GSoC project. It just\n> doesn't seem like a big enough feature to take the whole summer. In the\n> schedule, there is a week of implementing \"git add -p\n> --add-with-message\". It seems like that should be hours, not days.\n> \n> I wonder if it could be rolled into a more comprehensive proposal\n> concerning commit workflows (though I admit, I don't personally have any\n> other ideas in the area).\n> \n> -Peff\n\nAhh ok, I will do something else then.\n\n> PS Daniel (and other potential GSoC'ers who are reading), please don't\n> take this as discouragement of presenting proposals that aren't on the\n> ideas wiki. I really really like the concept of somebody working on\n> their own itch, as I think they tend to have a clearer idea of what the\n> solution should look like. I'm just concerned this particular proposal\n> isn't big enough.\n\nThank you. Maybe if I don't find something else to do this summer I will\nimplement this instead outside of GSoC.\n\n\nThank you everybody who commented on my proposal, it was a good learning\nexperience.\n\nThank you everybody who has contributed to git for making it so awesome.\n\n\nBest regards,\n\nDaniel\n\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\ncommit message before the commit itself.\n\nCurrently this can be done manually using \"-F <file>, --file=<file>\" in\ngit commit but we can do better than that. This projects involves making\na built in system for persistently storing commit messages while they\nare in the process of being written. Then modifying various git commands\nto use this specifically changes to git add [--interactive | -i] to add\nan 'am' or similar command to allow adding a file and then prompting for\na message about the changes to that file. Also changes to git add\n[--patch | -p] to add 'm' and 'c' options to git add --patch to allow\nthe addition of a message for the current hunk ('m') and to do a commit\n(prompting for review) before returning to the hunk currently in focus\n('c').\n\n=== How would you measure its success or failure? ===\n* The creation of a good persistent storage mechanism for storing commit\nmessages while they are being edited \n* The creation of a good API for editing commit messages for work that\nis in 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\ncommunity.\n\n=== The project in more detail. ===\nA backend for storing the commit message that is being worked on,\nprobably using a file called COMMIT_NEXTMSG in .git/ (following the\nstandard set by COMMIT_EDITMSG). With a file format for describing the\ncommit message, this would be a normal text file but with the use of\n\"/path/to/file.extension:[line number | line-range:] <detail about this\npart of the commit>\" to store the various bits of commit message as they\nare added. Since using a simple COMMIT_NEXTMSG file would not work\nacross 'git stash' and branch-switching it would probably need to be\nattached to a object using git notes. Fortunately it is probably\npossible to use the current HEAD when branch switching and to use the\n'W' commit of the working tree when using git stash.\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\nor if [-n | --nextmsg] is used then it just uses the contents of the\nfile (of course [-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\nthe hunk they were looking at and 'n' takes them straight back to the\nhunk. This makes it easier to separate out multiple atomic changes from\na file.\n\n==== Use cases ====\nPhilip is making an atomic commit that touches several files and wants\nto be able to add to the commit message for each one while the changes\nhe made are still fresh in his memory but doesn't want to do a commit\nfor each change as then the project won't compile for some commits.\n\nAndrew has been hacking on a file and made lots of changes in various\nplaces in the file. These changes should be split up into atomic commits\nwhich 'git add --patch' makes easy, however it would be even faster if\nwhen looking at hunks to add them the commit message could be edited as\nthis is faster than the two pass add hunks, exit 'git add --patch', run\n'git diff --cached' and in a separate terminal write the commit message.\nHopefully this means that Andrew will be more likely to split his\nchanges into atomic commits rather than just adding the file containing\nmultiple sets of changes.\n\n=== Schedule ===\nCreate a mechanism for persistently storing the commit message which is\ncurrently being written and an API for modifying it and then write three\ndifferent mechanisms which use it in order to ensure that the API works\nproperly. Having ensured that it works properly from an editing point of\nview modify git commit to use it.\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\nsuggested.\n* 9th August check all the documentation and make all the necessary\nchanges. Write any more additional pieces of documentation necessary\ne.g. tutorials.\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\nany bugs that are found subsequently. Continue lurking on the mailing\nlist and #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* git notes\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\nreally in a fit state for use by anyone else and we never got around to\ntalking about licenses. I wrote the User Management system, and ran the\nserver (tomcat), version control (SVN after a vote by the group which\nhad in general not used VCSs before) and unit testing (junit4). I also\nrewrote part of the comms system and wrote a test client for it. This\nproject was also in Java. We did a lot of communication in person but we\nalso used Google wave and Google docs. There were five developers in my\ngroup and we had 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\n8.7ksloc of Java and GWT. This code is available under the GPL v2 but\nsince we haven't done a release yet it isn't linked to from anywhere. I\nwas the only developer on this project, I communicated with my\nsupervisor both in person 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\n#lounge on irc.worldforge.org, but I also used the mailing list\n(particularly for the submission of patches). I had CVS commit rights\nbut they have subsequently moved to Git and I have only been lurking on\ntheir mailing list 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 have 18 repositories on my local machine. I haven't\nused it in a multi-user manner as in general it has been just me working\non 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\ngo as well as it was supposed to.\n\nI have been lurking on #git for a few days now and I have tried to\nprovide support where I could for those questions which were asked when\nI was watching. I have joined the git mailing list and while I haven't\nbeen reading 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\nlook at them. I would ensure that I listened to advice given to me and\nacted upon 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\nmake suggestions on how to do it better early on in the project. I would\nalso remain on #git and increase the proportion of mailing list emails\nwhich I read.\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.\n'charon' mentioned that 'git commit --amend' can be used to amend the\nlast commit message and that 'git commit --amend --only' can be used to\namend the last commit message even once the index has become dirty due\nto preparation for the next commit. Alternatively 'git rebase\n--interactive's squash feature could be used to do something similar\nhowever I prefer to avoid rewriting history unnecessarily and I think\nthat this project would make it far easier than using git commit --amend\n--only and avoids problems with changes which have been pushed to a\nremote repository.\n\nI posted a link to this proposal to the mailing list on the\n[http://article.gmane.org/gmane.comp.version-control.git/143418 28th\nMarch] and to #git on the\n[http://colabti.org/irclogger/irclogger_log/git?date=2010-03-28#l1863\n28th] and\n[http://colabti.org/irclogger/irclogger_log/git?date=2010-03-29#l2266\n29th] of March.\n"}]}