{"thread":{"id":"30647","subject":"How does Git's maintenance policy handle topics that don't start from \"master?\"","startedAt":"2012-05-29T20:33:45Z","lastAt":"2012-05-29T23:16:40Z","messageCount":6,"participants":["Steven E. Harris","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"192434","messageId":"m21um2682e.fsf@Spindle.sehlabs.com","threadId":"30647","inReplyTo":null,"subject":"How does Git's maintenance policy handle topics that don't start from \"master?\"","fromName":"Steven E. Harris","fromEmail":"seh@panix.com","sentAt":"2012-05-29T20:33:45Z","receivedAt":"2012-05-29T20:33:45Z","isPatch":false,"sender":{"key":"seh@panix.com","avatar":"https://gravatar.com/avatar/d59ec0f7c010ee73cd67db381a5b865206fed17fd4278f12cdb6277db30033fc?d=mp&s=160"},"body":"I've read the /Addendum to \"MaintNotes\"/ document¹ several times in the\nlast few years, but in the process of trying to employ the policy with\nmy current team, our progress is stuck on a case that isn't addressed by\nthe policy -- directly, anyway.\n\nIn the policy section \"Handle the remaining patches,\" the first clause\nreads as follows:\n\n,----[ First case for remaining patches ]\n| Anything unobvious that is applicable to 'master' (in other\n| words, does not depend on anything that is still in 'next'\n| and not in 'master') is applied to a new topic branch that\n| is forked from the tip of 'master'.  This includes both\n| enhancements and unobvious fixes to 'master'.\n`----\n\nIt addresses topics that can be built on top of the \"master\" branch,\nthese topics not depending on anything only available outside the\n\"master\" branch, such as in the \"next\" branch. This policy is focusing\non the receiver and integrator of patches, rather than the author, but\nit's not hard to infer that an author should start his work from the\n\"master\" branch in order for his patches to be eligible for treatment by\nthis clause.\n\nWhat about the case where an author started his work from the \"next\"\nbranch instead? He may have submitted an earlier batch of work that's\nstill cooking in \"next,\" and now he needs to build something else that\ncan take advantage of that earlier work. It's clear that if he starts\nfrom \"next\" and relies on that earlier work, then his later work is not\nindependent and cannot possibly graduate to the \"master\" branch unless\nand until his earlier work graduates too.\n\nIs the Git policy on such dependency simply, \"Don't do that?\"\n\nConsider a situation where the earlier topic branch's contribution\ncooking in \"next\" is looking good and everyone is feeling confident that\nit's going to graduate, and our poor author /needs/ to get started on\nhis next task that would make use of the earlier work. If he does start\nhis new topic branch from \"next\" -- or maybe starts it from his earlier\ntopic branch instead -- what will go wrong later? Is there a part of the\npolicy that addresses this case that I missed?\n\n\nFootnotes: \n¹ http://www.kernel.org/pub/software/scm/git/docs/v1.7.10.1/howto/maintain-git.txt\n\n-- \nSteven E. Harris\n"},{"id":"192439","messageId":"m2wr3u4r5n.fsf@Spindle.sehlabs.com","threadId":"30647","inReplyTo":"m21um2682e.fsf@Spindle.sehlabs.com","subject":"Re: How does Git's maintenance policy handle topics that don't start from \"master?\"","fromName":"Steven E. Harris","fromEmail":"seh@panix.com","sentAt":"2012-05-29T21:24:20Z","receivedAt":"2012-05-29T21:24:20Z","isPatch":false,"sender":{"key":"seh@panix.com","avatar":"https://gravatar.com/avatar/d59ec0f7c010ee73cd67db381a5b865206fed17fd4278f12cdb6277db30033fc?d=mp&s=160"},"body":"\"Steven E. Harris\" <seh@panix.com> writes:\n\n> Is there a part of the policy that addresses this case that I missed?\n\nAfter posting I discovered the \"SubmittingPatches\" document¹, which does\naddress part of my inquiry:\n\n,----[ Decide what to base your work on ]\n| - A new feature should be based on 'master' in general. If the new\n|    feature depends on a topic that is in 'pu', but not in 'master',\n|    base your work on the tip of that topic.\n| \n| - Corrections and enhancements to a topic not yet in 'master' should\n|    be based on the tip of that topic. If the topic has not been merged\n|    to 'next', it's alright to add a note to squash minor corrections\n|    into the series.\n| \n| - In the exceptional case that a new feature depends on several topics\n|    not in 'master', start working on 'next' or 'pu' privately and send\n|    out patches for discussion. Before the final merge, you may have to\n|    wait until some of the dependent topics graduate to 'master', and\n|    rebase your work.\n`----\n\nThe last one in particular implies that the topic branch will not be fit\nfor serious consideration until its dependencies have themselves\ngraduated to \"master.\"\n\nFootnotes: \n¹ https://raw.github.com/git/git/master/Documentation/SubmittingPatches\n-- \nSteven E. Harris\n"},{"id":"192441","messageId":"7vbol63ccs.fsf@alter.siamese.dyndns.org","threadId":"30647","inReplyTo":"m21um2682e.fsf@Spindle.sehlabs.com","subject":"Re: How does Git's maintenance policy handle topics that don't start from \"master?\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-29T21:29:23Z","receivedAt":"2012-05-29T21:29:23Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Steven E. Harris\" <seh@panix.com> writes:\n\n> What about the case where an author started his work from the \"next\"\n> branch instead? He may have submitted an earlier batch of work that's\n> still cooking in \"next,\" and now he needs to build something else that\n> can take advantage of that earlier work.\n\nIt often is clear that the follow-on topic depends on an earlier\ntopic branch (mostly because the contributor is aware of it and\nstate it in the message).  An obvious thing to do in such a case is\nto create a new branch to queue that topic starting at the tip of\nthe earlier topic.  Note that this is never from the tip of \"next\",\nas it is very unlikely that such a follow-on topic depends on\neverything that is not in \"master\" yet.\n\nSometimes a new work depends on multiple topics that are still\ncooking, and *all* of these topics that the new work depends on are\nin good shape.  In such a case, I create a new branch by merging\nthese prerequisite topics and then queue new work there.  Obviously\nthe new work is taken hostage to *all* of its dependent topics, and\ncannot graduate until all of the base topics graduate.\n\nSometimes a new work depends on one topic that is still cooking in\n\"next\", *and* also needs updates made by other topics that are\nalready in \"master\".  You can guess what should happen---take the\ntip of that topic that is still cooking in \"next\", merge the commit\non \"master\" that adds other necessary bits, and then that becomes\nthe base of the new topic.  The \"commit that adds other necessary\nbits\" could be the tip of \"master\" (easiest for me, but it makes the\nnew topic unmergeable to \"maint\" later) or the tip of an old topic\nthat was merged to \"master\" (more work for me, but it is worth if\nboth the other old topic and the topic that is cooking in \"next\" are\nmeant to be merged to \"maint\" later, and the new work is also meant\nto eventually be merged to \"maint\").\n\nIn a rare cases where a new work depends on millions of uncooked\ntopics, we simply reject the follow-on series and tell the submitter\nto wait until the dust settles, but in practice it does not happen\nvery often.\n\nIn other words, the \"policy\" is not a mechanical recipe to be\nfollowed by brainless monkeys; the integrator needs to follow the\ncommon sense of keeping the resulting topic branch mergeable to as\nmany relevant contexts as necessary.\n\nAnd the contributor can help in this process, as well.\n"},{"id":"192442","messageId":"m2sjei4pvq.fsf@Spindle.sehlabs.com","threadId":"30647","inReplyTo":"7vbol63ccs.fsf@alter.siamese.dyndns.org","subject":"Re: How does Git's maintenance policy handle topics that don't start from \"master?\"","fromName":"Steven E. Harris","fromEmail":"seh@panix.com","sentAt":"2012-05-29T21:51:53Z","receivedAt":"2012-05-29T21:51:53Z","isPatch":false,"sender":{"key":"seh@panix.com","avatar":"https://gravatar.com/avatar/d59ec0f7c010ee73cd67db381a5b865206fed17fd4278f12cdb6277db30033fc?d=mp&s=160"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> It often is clear that the follow-on topic depends on an earlier topic\n> branch (mostly because the contributor is aware of it and state it in\n> the message).  An obvious thing to do in such a case is to create a\n> new branch to queue that topic starting at the tip of the earlier\n> topic.  Note that this is never from the tip of \"next\", as it is very\n> unlikely that such a follow-on topic depends on everything that is not\n> in \"master\" yet.\n\nThank you for the thorough reply.\n\nI want to make sure that I understand the main hazard that the policy\naims to avoid. If an author bases a topic branch on the tip of \"next,\"\nthen, later, it will not be possible to merge his work to \"master\"\nwithout implicitly accepting all of \"next\" (or, at least the part of\n\"next\" the precedes this topic branch) into \"master.\" We are trying to\navoid merging \"upward\" from \"next\" to \"master\" like that, and prefer to\ntake the topics to \"master\" directly rather than implicitly by way of\ntheir inclusion in \"next.\"\n\nWhat isn't so clear to me, though, is /why/ this don't-merge-from-\"next\"\nrule is so important. Say that we had one topic \"t1\" depart from \"next,\"\nand then another topic \"t2\" depart from \"t1,\" and both have been cooking\nin \"next,\" with good results.\n\n  ---o---o---o---o  master\n                  \\\n                   o---o---o---o---o---M---o---o next\n                        \\     /       /\n                         o---o t1    /\n                              \\     /\n                               o---o t2\n\nIf we wanted to graduate these two topics to \"master,\" we /could/ merge\nfrom commit M back to \"master,\" though here I deliberately included the\nnefarious commit X, which shows other interleaved contributions along\n\"next\" that are also part of the M commit.\n\nWhat about this case, where topics \"t1\" and \"t2\" did depart from\n\"master,\" and are doing well along \"next\" together as of commit M.\n\n  ---o---o---o---o  master\n      \\   \\       \\\n       \\   o---o---o---M---o---o next\n        \\     /       /\n         o---o t1    /\n          \\         /\n           o---o---o t2\n\nThe Git policy as I understand it prescribes that we merge from the tips\nof \"t1\" and \"t2\" back to master, not from a commit like M. What harm\nwould come from merging from M in this case? Future archaeology of topic\nprovenance?\n\n-- \nSteven E. Harris\n"},{"id":"192449","messageId":"7vzk8q1t9r.fsf@alter.siamese.dyndns.org","threadId":"30647","inReplyTo":"m2sjei4pvq.fsf@Spindle.sehlabs.com","subject":"Re: How does Git's maintenance policy handle topics that don't start from \"master?\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-29T23:06:56Z","receivedAt":"2012-05-29T23:06:56Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Steven E. Harris\" <seh@panix.com> writes:\n\n> What isn't so clear to me, though, is /why/ this don't-merge-from-\"next\"\n> rule is so important. Say that we had one topic \"t1\" depart from \"next,\"\n> and then another topic \"t2\" depart from \"t1,\" and both have been cooking\n> in \"next,\" with good results.\n>\n>   ---o---o---o---o  master\n>                   \\\n>                    o---o---o---o---o---M---o---o next\n>                         \\     /       /\n>                          o---o t1    /\n>                               \\     /\n>                                o---o t2\n>\n> If we wanted to graduate these two topics to \"master,\" we /could/ merge\n> from commit M back to \"master,\" though here I deliberately included the\n> nefarious commit X, which shows other interleaved contributions along\n> \"next\" that are also part of the M commit.\n\nI do not see any X above, but I think you meant the commits in\nmaster..M that are not reachable from either t1 and t2.\n\nAnd I think you answered your own question.  These \"master..M ^t1\n^t2\" commits are topics that are *not* part of t1 nor t2.  If you\ndeem all of them are good enough for your master, it is perfectly\nfine to merge M to master.  In reality, it is more cumbersome to\nthink about what is and what is not yet in M and decide if the set\nof changes that happen to be in M match exactly what you want to\nmerge, than knowing that you exactly want to have t1 and t2 and\nnothing else in your master during this integration run and merge\nonly these two topics.\n\nThe same answer to the other picture.  If you can figure out an\nappropriate commit M that has what you want, go right ahead and\nmerge that to 'master'; I do not see any harm there.  I personally\ndo not think it is worth the effort to figure out which commit\nbetween master..next that M is, and verify master..M contains\neverything you want and nothing you don't.  Merging t1 and t2\nexplicitly, when you know they are the only thing you want to merge,\nis much simpler and less error prone.\n\n> What about this case, where topics \"t1\" and \"t2\" did depart from\n> \"master,\" and are doing well along \"next\" together as of commit M.\n>\n>   ---o---o---o---o  master\n>       \\   \\       \\\n>        \\   o---o---o---M---o---o next\n>         \\     /       /\n>          o---o t1    /\n>           \\         /\n>            o---o---o t2\n>\n> The Git policy as I understand it prescribes that we merge from the tips\n> of \"t1\" and \"t2\" back to master, not from a commit like M. What harm\n> would come from merging from M in this case? Future archaeology of topic\n> provenance?\n"},{"id":"192450","messageId":"7vsjei1stj.fsf@alter.siamese.dyndns.org","threadId":"30647","inReplyTo":"7vzk8q1t9r.fsf@alter.siamese.dyndns.org","subject":"Re: How does Git's maintenance policy handle topics that don't start from \"master?\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-05-29T23:16:40Z","receivedAt":"2012-05-29T23:16:40Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> \"Steven E. Harris\" <seh@panix.com> writes:\n>\n>> What about this case, where topics \"t1\" and \"t2\" did depart from\n>> \"master,\" and are doing well along \"next\" together as of commit M.\n>>\n>>   ---o---o---o---o  master\n>>       \\   \\       \\\n>>        \\   o---o---o---M---o---o next\n>>         \\     /       /\n>>          o---o t1    /\n>>           \\         /\n>>            o---o---o t2\n>>\n>> The Git policy as I understand it prescribes that we merge from the tips\n>> of \"t1\" and \"t2\" back to master, not from a commit like M. What harm\n>> would come from merging from M in this case? Future archaeology of topic\n>> provenance?\n\nYou would also have to think about what you write to explain that\nmerge of M into 'master' in the commit log message.  In the above\nspecial case where 'next' happened to have had only t1 and t2 when\nyou decided to merge to 'master', you could say \"Merge t1 and t2 to\nachieve X\", but in the earlier example (elided), it is not clear\nwhat random bits you are merging with it.\n\nCompared to that, if you merge t1 and t2 separately, you can say \"I\nam merging t1 topic that does X\", and readers of \"git log master\"\n(better yet \"git log --first-parent master\") would understand that\nthe master branch after that commit can do X (and everything before\nthat commit does not).\n"}]}