{"thread":{"id":"33290","subject":"patch series vs. multiple files changed in a commit; storytelling history vs. literal creation history","startedAt":"2013-03-26T21:21:43Z","lastAt":"2013-03-26T22:03:29Z","messageCount":2,"participants":["Matt McClure","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"212335","messageId":"CAJELnLE0FLrSYGHgS-cZmyQWO122-MuN7AeczUUVVposUg+qjw@mail.gmail.com","threadId":"33290","inReplyTo":null,"subject":"patch series vs. multiple files changed in a commit; storytelling history vs. literal creation history","fromName":"Matt McClure","fromEmail":"matthewlmcclure@gmail.com","sentAt":"2013-03-26T21:21:43Z","receivedAt":"2013-03-26T21:21:43Z","isPatch":false,"sender":{"key":"matthewlmcclure@gmail.com","avatar":"https://gravatar.com/avatar/a8cde96b0594204c8d4c48baa51c983af37dedfa2b7a846e27547b8d63d46e7c?d=mp&s=160"},"body":"I've read Documentation/SubmittingPatches, followed some of the\ndiscussion on this list, and looked over some of the recent commit\nhistory. I'm impressed by the strong culture of review that produces\nreadable patches and commit messages, but I think there are some gaps\nin my understanding of the prevailing process here.\n\nMost of the code I've worked on has been closed source, and the commit\nhistories tend to reflect what I'd call the literal \"creation\nhistory\". Reading the Git history, my impression is that it reflects a\ndifferent \"storytelling\" history. In some cases, that might be the\nsame as the creation history, but in general the emphasis is on\ntelling a coherent story of the changes to the other developers rather\nthan communicating all the messy details of how you arrived at the\norder of that story. Is that right?\n\nWhat are the Git project's rules of thumb for when to create a patch\nseries vs. putting changes to multiple files in a single commit/patch?\n\nAs a patch series evolves before landing on an upstream branch, do you\ntypically make corrections to the original series in new commits, or\nupdate the respective commits from the original series in a new series\nof analogous commits?\n\n-- \nMatt McClure\nhttp://www.matthewlmcclure.com\nhttp://www.mapmyfitness.com/profile/matthewlmcclure\n"},{"id":"212347","messageId":"7vli99stse.fsf@alter.siamese.dyndns.org","threadId":"33290","inReplyTo":"CAJELnLE0FLrSYGHgS-cZmyQWO122-MuN7AeczUUVVposUg+qjw@mail.gmail.com","subject":"Re: patch series vs. multiple files changed in a commit; storytelling history vs. literal creation history","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2013-03-26T22:03:29Z","receivedAt":"2013-03-26T22:03:29Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matt McClure <matthewlmcclure@gmail.com> writes:\n\n> I've read Documentation/SubmittingPatches, followed some of the\n> discussion on this list, and looked over some of the recent commit\n> history. I'm impressed by the strong culture of review that produces\n> readable patches and commit messages, but I think there are some gaps\n> in my understanding of the prevailing process here.\n>\n> Most of the code I've worked on has been closed source, and the commit\n> histories tend to reflect what I'd call the literal \"creation\n> history\". Reading the Git history, my impression is that it reflects a\n> different \"storytelling\" history. In some cases, that might be the\n> same as the creation history, but in general the emphasis is on\n> telling a coherent story of the changes to the other developers rather\n> than communicating all the messy details of how you arrived at the\n> order of that story. Is that right?\n\nWe do not try to keep records of \"oops, the previous was wrong\" when\nwe can easily tell the previous was wrong.  Usually such a shallow\nmistake that can be spotted during the review is not worth keeping.\n\nFor example, the 4 patch series I posted today had three iterations\nof botched attempts that were never even published.  I am sure other\npeople do the same for their initial round for their patches, and\nany message on this list whose subject begins with \"[PATCH vN X/Y]\"\nfor N > 2 are rewritten betterment based on list feedback.\n\nOur history tends to become a coherent story because of this.\n\nIt is a different story for more involved changes that cook in\n'next' for a while and then later turns out to have flaws. We update\nthem with follow-up fixes and at that point, we do have records of\nmistakes. They often are tricky cases that are worth recording, as\npeople can later make similar kinds of mistakes in other parts of\nthe codebase.\n\nThe early part of the history back when Linus was running the show\nis somewhat different; you see more reverts and rewrites. But even\nback then, there were more experimental changes that were rewritten\nthan the changes that were finally committed to the history.\n"}]}