{"thread":{"id":"55691","subject":"[PATCH] Documentation/howto: tracking git.git","startedAt":"2021-05-14T12:50:02Z","lastAt":"2021-05-16T01:01:59Z","messageCount":5,"participants":["Bagas Sanjaya","Junio C Hamano","Đoàn Trần Công Danh"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"424580","messageId":"20210514124925.39229-1-bagasdotme@gmail.com","threadId":"55691","inReplyTo":null,"subject":"[PATCH] Documentation/howto: tracking git.git","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-14T12:49:26Z","receivedAt":"2021-05-14T12:50:02Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Document how to track git.git repository for Git development.\n\nSigned-off-by: Bagas Sanjaya <bagasdotme@gmail.com>\n---\n Documentation/Makefile                  |  1 +\n Documentation/howto/tracking-gitgit.txt | 79 +++++++++++++++++++++++++\n 2 files changed, 80 insertions(+)\n create mode 100644 Documentation/howto/tracking-gitgit.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 2aae4c9cbb..2b5b8b28b0 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -84,6 +84,7 @@ SP_ARTICLES += howto/rebase-from-internal-branch\n SP_ARTICLES += howto/keep-canonical-history-correct\n SP_ARTICLES += howto/maintain-git\n SP_ARTICLES += howto/coordinate-embargoed-releases\n+SP_ARTICLES += howto/tracking-gitgit\n API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))\n SP_ARTICLES += $(API_DOCS)\n \ndiff --git a/Documentation/howto/tracking-gitgit.txt b/Documentation/howto/tracking-gitgit.txt\nnew file mode 100644\nindex 0000000000..61dbd2540b\n--- /dev/null\n+++ b/Documentation/howto/tracking-gitgit.txt\n@@ -0,0 +1,79 @@\n+From: Bagas Sanjaya <bagasdotme@gmail.com>\n+Date: Fri, 14 May 2021 13:26:33 +0700\n+Subject: Tracking git.git\n+Abstract: How to track git.git repository for Git development\n+Content-type: text/asciidoc\n+\n+Tracking git.git\n+================\n+\n+This short document shows how to track git.git (source code repository\n+for Git) for purposes of Git development.\n+\n+Available Branches\n+------------------\n+\n+There are several branches on git.git with different purposes:\n+\n+master::\n+This is the most stable branch. Changes (topics) that are merged\n+to master should have been stabilized in next and suitable for\n+production use. Feature releases (vX.Y.0) are cut from this\n+branch.\n+\n+next::\n+This is where topics that haven't been yet merged to master are\n+stabilized and tested for breakage and regressions. It gives\n+a summary forecast of what next batch of topics that will be\n+merged to master looks like.\n+\n+seen::\n+This is the most bleeding edge branch where all excited\n+developments happened. All proposed topics are queued in seen\n+by the maintainer. However, these may be buggy (have breakage or\n+regressions). When topics queued are deemed good and ready for\n+inclusion, they are graduated to next for stabilization.\n+\n+maint::\n+This branch is used for preparing maintenance releases. Bugfixes\n+for feature release (vX.Y.0) are accumulated in maint. Then at\n+some point, the tip of the branch is tagged with vX.Y.Z.\n+\n+todo::\n+This contains helper tools written by the maintainer to ease\n+maintaining Git. Also, \"What's cooking in Git\" messages are\n+prepared in todo before being sent to the mailing list.\n+\n+Tracking\n+--------\n+\n+If you don't have git.git clone handy, you can obtain one by:\n+\n+----\n+$ git clone https://github.com/git/git.git git\n+----\n+\n+Now you can start hacking your topics. Don't forget to read\n+`Documentation/SubmittingPatches` for instructions on patch\n+submission.\n+\n+After some time, there will be updates to git.git. First, fetch them:\n+\n+----\n+$ git fetch origin\n+----\n+\n+Then pull the updates.\n+\n+ - For `master`, `next`, `maint`, and `todo`, you can do fast-forward\n+   pull:\n+\n+ $ git pull --ff-only\n+\n+ - For `seen`, DO NOT pull with `git pull`. This is because seen is\n+   in constant flux, and most often your local seen is divergent from\n+   the origin, caused by force-push from the maintainer. Attempting\n+   to pull either via merge or rebase will most likely end in\n+   conflict. Instead, pull by resetting the local seen to the origin:\n+\n+ $ git reset --hard origin/seen\n\nbase-commit: df6c4f722c94641d5a9ea5496511f7043433abc2\n-- \n2.25.1\n\n"},{"id":"424583","messageId":"xmqqwns177cv.fsf@gitster.g","threadId":"55691","inReplyTo":"20210514124925.39229-1-bagasdotme@gmail.com","subject":"Re: [PATCH] Documentation/howto: tracking git.git","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-14T13:49:52Z","receivedAt":"2021-05-14T13:49:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya <bagasdotme@gmail.com> writes:\n\n> +Available Branches\n> +------------------\n> +\n> +There are several branches on git.git with different purposes:\n> +\n> +master::\n> +This is the most stable branch. Changes (topics) that are merged\n> +to master should have been stabilized in next and suitable for\n> +production use. Feature releases (vX.Y.0) are cut from this\n> +branch.\n\nIsn't \"maint\" meant to be more stable?\n\n> +next::\n> +This is where topics that haven't been yet merged to master are\n> +stabilized and tested for breakage and regressions. It gives\n> +a summary forecast of what next batch of topics that will be\n> +merged to master looks like.\n> +\n> +seen::\n> +This is the most bleeding edge branch where all excited\n> +developments happened. All proposed topics are queued in seen\n> +by the maintainer. However, these may be buggy (have breakage or\n> +regressions). When topics queued are deemed good and ready for\n> +inclusion, they are graduated to next for stabilization.\n\nThis is inconsistent with what has been written elsewhere about this\nintegration branch.  In short, you should not read anything more\nthan \"the maintainer happens to have seen these topics\" out of the\nfact that a topic is in 'seen'.  Not all proposed topics will be in\nthis branch, and a branch that was in 'seen' on one day may not be\nthere the next day, but that does not mean anything (certainly it\ndoes not mean the topic has been \"rejected\").\n\n> +Tracking\n> +--------\n> +\n> +If you don't have git.git clone handy, you can obtain one by:\n> +\n> +----\n> +$ git clone https://github.com/git/git.git git\n> +----\n> +\n> +Now you can start hacking your topics. Don't forget to read\n> +`Documentation/SubmittingPatches` for instructions on patch\n> +submission.\n> +\n> +After some time, there will be updates to git.git. First, fetch them:\n> +\n> +----\n> +$ git fetch origin\n> +----\n> +\n> +Then pull the updates.\n> +\n> + - For `master`, `next`, `maint`, and `todo`, you can do fast-forward\n> +   pull:\n> +\n> + $ git pull --ff-only\n\nI do not see a point in doing this for all of these branches, and\nI'd rather not to see this recommended to people who \"track to\ndevelop\" at all.  It may make sense to do so if you do not do any\ndevelopment of your own and will always stay on 'master' to check\nout, build, test and install from the upstream, though.\n\nFor those who track to develop\", if you want a reference point to\nwork from, you can do \"git fetch origin\" and then run\n\n    $ git checkout -b mytopic origin/master\n\nfor a new feature, and\n\n    $ git checkout -b myfix origin/maint\n\nfor a fix.  You can track your progress with\n\n    $ git log origin/master..mytopic\n    $ git log origin/master..myfix\n\nIf you are fixing a longstanding bug, you may even want to do\n\n    $ git checkout -b myfix-for-2.29-and-above v2.29.3\n    $ git log origin/master..myfix-for-2.29-and-above\n\nTo test your various topics, you would then do\n\n    $ git checkout -B trial origin/master\n    $ git merge mytopic\n    $ git merge myfix\n    ... build, test, install, employ it for daily use ...\n\nAnd you can make sure you do not step on toes of others by doing\ntrial merges\n\n    $ git checkout -B trial origin/seen ;# or origin/next\n    $ git merge mytopic\n    $ git merge myfix\n    ... build and test\n\nwhich is highly recommended.  This will give you a chance to notice\nwho, if any, are working in areas of the codebase that potentially\noverlaps with what you are working on before you even send out your\nseries for review.\n\n> + - For `seen`, DO NOT pull with `git pull`. This is because seen is\n> +   in constant flux, and most often your local seen is divergent from\n> +   the origin, caused by force-push from the maintainer. Attempting\n> +   to pull either via merge or rebase will most likely end in\n> +   conflict. Instead, pull by resetting the local seen to the origin:\n> +\n> + $ git reset --hard origin/seen\n\nEven better, do not even create your own 'seen' branch at all.  If\nyou are interested in what is going on\n\n    $ git log --first-parent --oneline origin/master..origin/seen\n\nmight be worth paying attention to, and checking out the tip of\ntopics of other people you seen in the output and playing with it on\na detached HEAD may also be useful, and if you find bugs in other's\nwork, you can futz with the code from that commit and you may end up\nwith a patch you can send as an improvement suggestion to the\noriginal author of the topic.  But 'seen' as a whole is rarely of\ninterest, except for the purpose of learning what other topics may\nbe in flight.  Nobody sane is supposed to be running the version\nfrom 'seen'; after all, the selection criteria of the topics in it\nis \"some of the topics that the maintainer happened to have seen\",\nand not even \"these topics are interesting, promising and are wished\nto be in 'next' someday\".\n\n"},{"id":"424587","messageId":"YJ6W50M+EJlIO1GJ@danh.dev","threadId":"55691","inReplyTo":"xmqqwns177cv.fsf@gitster.g","subject":"Re: [PATCH] Documentation/howto: tracking git.git","fromName":"Đoàn Trần Công Danh","fromEmail":"congdanhqx@gmail.com","sentAt":"2021-05-14T15:27:35Z","receivedAt":"2021-05-14T15:27:42Z","isPatch":true,"sender":{"key":"congdanhqx@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42673067?v=4"},"body":"On 2021-05-14 22:49:52+0900, Junio C Hamano <gitster@pobox.com> wrote:\n> Bagas Sanjaya <bagasdotme@gmail.com> writes:\n> \n> > +Available Branches\n> > +------------------\n> > +\n> > +There are several branches on git.git with different purposes:\n> > +\n> > +master::\n> > +This is the most stable branch. Changes (topics) that are merged\n> > +to master should have been stabilized in next and suitable for\n> > +production use. Feature releases (vX.Y.0) are cut from this\n> > +branch.\n> \n> Isn't \"maint\" meant to be more stable?\n> \n> > +next::\n> > +This is where topics that haven't been yet merged to master are\n> > +stabilized and tested for breakage and regressions. It gives\n> > +a summary forecast of what next batch of topics that will be\n> > +merged to master looks like.\n> > +\n> > +seen::\n> > +This is the most bleeding edge branch where all excited\n> > +developments happened. All proposed topics are queued in seen\n> > +by the maintainer. However, these may be buggy (have breakage or\n> > +regressions). When topics queued are deemed good and ready for\n> > +inclusion, they are graduated to next for stabilization.\n> \n> This is inconsistent with what has been written elsewhere about this\n> integration branch.  In short, you should not read anything more\n> than \"the maintainer happens to have seen these topics\" out of the\n> fact that a topic is in 'seen'.  Not all proposed topics will be in\n> this branch, and a branch that was in 'seen' on one day may not be\n> there the next day, but that does not mean anything (certainly it\n> does not mean the topic has been \"rejected\").\n\nWell, I think most of this document's points has been written in\nDocumentation/howto/maintain-git.txt and\nDocumentation/SubmittingPatches.txt.\n\nWith only 2 above points, I think if we have this document in,\nwe'll have more things to maintain :shrug:\n\n-- \nDanh\n"},{"id":"424629","messageId":"cbbde4f4-3e10-2c08-6ca1-6f22f8497194@gmail.com","threadId":"55691","inReplyTo":"xmqqwns177cv.fsf@gitster.g","subject":"Re: [PATCH] Documentation/howto: tracking git.git","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-15T03:32:27Z","receivedAt":"2021-05-15T03:32:34Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 14/05/21 20.49, Junio C Hamano wrote:\n> Bagas Sanjaya <bagasdotme@gmail.com> writes:\n> \n>> +Available Branches\n>> +------------------\n>> +\n>> +There are several branches on git.git with different purposes:\n>> +\n>> +master::\n>> +This is the most stable branch. Changes (topics) that are merged\n>> +to master should have been stabilized in next and suitable for\n>> +production use. Feature releases (vX.Y.0) are cut from this\n>> +branch.\n> \n> Isn't \"maint\" meant to be more stable?\n> \n\nI think \"maint\" is maintenance branch for latest feature release.\nFor feature stabilization it happens on \"main\", so \"master\" is fully\npolished.\n\n>> +next::\n>> +This is where topics that haven't been yet merged to master are\n>> +stabilized and tested for breakage and regressions. It gives\n>> +a summary forecast of what next batch of topics that will be\n>> +merged to master looks like.\n>> +\n>> +seen::\n>> +This is the most bleeding edge branch where all excited\n>> +developments happened. All proposed topics are queued in seen\n>> +by the maintainer. However, these may be buggy (have breakage or\n>> +regressions). When topics queued are deemed good and ready for\n>> +inclusion, they are graduated to next for stabilization.\n> \n> This is inconsistent with what has been written elsewhere about this\n> integration branch.  In short, you should not read anything more\n> than \"the maintainer happens to have seen these topics\" out of the\n> fact that a topic is in 'seen'.  Not all proposed topics will be in\n> this branch, and a branch that was in 'seen' on one day may not be\n> there the next day, but that does not mean anything (certainly it\n> does not mean the topic has been \"rejected\").\n> \n>> +Tracking\n>> +--------\n>> +\n>> +If you don't have git.git clone handy, you can obtain one by:\n>> +\n>> +----\n>> +$ git clone https://github.com/git/git.git git\n>> +----\n>> +\n>> +Now you can start hacking your topics. Don't forget to read\n>> +`Documentation/SubmittingPatches` for instructions on patch\n>> +submission.\n>> +\n>> +After some time, there will be updates to git.git. First, fetch them:\n>> +\n>> +----\n>> +$ git fetch origin\n>> +----\n>> +\n>> +Then pull the updates.\n>> +\n>> + - For `master`, `next`, `maint`, and `todo`, you can do fast-forward\n>> +   pull:\n>> +\n>> + $ git pull --ff-only\n> \n> I do not see a point in doing this for all of these branches, and\n> I'd rather not to see this recommended to people who \"track to\n> develop\" at all.  It may make sense to do so if you do not do any\n> development of your own and will always stay on 'master' to check\n> out, build, test and install from the upstream, though.\n> \n\nBut when someone clones git.git, Git will automatically checkout default\nbranch (which is \"master\") after cloning. If he wants to checkout other\nbranches, he had to \"git checkout next\" for example. I wrote it above\nunder the assumption that someone had already checkout other branches\nbefore.\n\n> For those who track to develop\", if you want a reference point to\n> work from, you can do \"git fetch origin\" and then run\n> \n>      $ git checkout -b mytopic origin/master\n> \n> for a new feature, and\n> \n>      $ git checkout -b myfix origin/maint\n> \n> for a fix.  You can track your progress with\n> \n>      $ git log origin/master..mytopic\n>      $ git log origin/master..myfix\n> \n\nI think git log above shows only commits that are on mytopic/myfix/\nwhatever that aren't on origin/master.\n\n> If you are fixing a longstanding bug, you may even want to do\n> \n>      $ git checkout -b myfix-for-2.29-and-above v2.29.3\n>      $ git log origin/master..myfix-for-2.29-and-above\n> \n> To test your various topics, you would then do\n> \n>      $ git checkout -B trial origin/master\n>      $ git merge mytopic\n>      $ git merge myfix\n>      ... build, test, install, employ it for daily use ...\n> \n> And you can make sure you do not step on toes of others by doing\n> trial merges\n> \n>      $ git checkout -B trial origin/seen ;# or origin/next\n>      $ git merge mytopic\n>      $ git merge myfix\n>      ... build and test\n> \n> which is highly recommended.  This will give you a chance to notice\n> who, if any, are working in areas of the codebase that potentially\n> overlaps with what you are working on before you even send out your\n> series for review.\n> \n>> + - For `seen`, DO NOT pull with `git pull`. This is because seen is\n>> +   in constant flux, and most often your local seen is divergent from\n>> +   the origin, caused by force-push from the maintainer. Attempting\n>> +   to pull either via merge or rebase will most likely end in\n>> +   conflict. Instead, pull by resetting the local seen to the origin:\n>> +\n>> + $ git reset --hard origin/seen\n> \n> Even better, do not even create your own 'seen' branch at all.  If\n> you are interested in what is going on\n> \n>      $ git log --first-parent --oneline origin/master..origin/seen\n> \n\nOK.\n\n> might be worth paying attention to, and checking out the tip of\n> topics of other people you seen in the output and playing with it on\n> a detached HEAD may also be useful, and if you find bugs in other's\n> work, you can futz with the code from that commit and you may end up\n> with a patch you can send as an improvement suggestion to the\n> original author of the topic.  But 'seen' as a whole is rarely of\n> interest, except for the purpose of learning what other topics may\n> be in flight.  Nobody sane is supposed to be running the version\n> from 'seen'; after all, the selection criteria of the topics in it\n> is \"some of the topics that the maintainer happened to have seen\",\n> and not even \"these topics are interesting, promising and are wished\n> to be in 'next' someday\".\n>\nThanks for your review.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"424669","messageId":"xmqqsg2n7awt.fsf@gitster.g","threadId":"55691","inReplyTo":"cbbde4f4-3e10-2c08-6ca1-6f22f8497194@gmail.com","subject":"Re: [PATCH] Documentation/howto: tracking git.git","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-05-16T00:57:38Z","receivedAt":"2021-05-16T01:01:59Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya <bagasdotme@gmail.com> writes:\n\n> On 14/05/21 20.49, Junio C Hamano wrote:\n>> Bagas Sanjaya <bagasdotme@gmail.com> writes:\n>> \n>>> +Available Branches\n>>> +------------------\n>>> +\n>>> +There are several branches on git.git with different purposes:\n>>> +\n>>> +master::\n>>> +This is the most stable branch. Changes (topics) that are merged\n>>> +to master should have been stabilized in next and suitable for\n>>> +production use. Feature releases (vX.Y.0) are cut from this\n>>> +branch.\n>> Isn't \"maint\" meant to be more stable?\n>> \n>\n> I think \"maint\" is maintenance branch for latest feature release.\n> For feature stabilization it happens on \"main\", so \"master\" is fully\n> polished.\n\nWith the status of being back-then-most polished plus only fixes and\nno unnecessary new features that can introduce unstability yet to be\ndiscovered, by definition 'maint' ought to be \"more stable\" than\n'master', no?\n\nIn any case, as Đoàn Trần Công Danh pointed out, I think we have\nmost of these written down elsewhere, and it is easier for readers\nif we can find a way to reorganize them and incorporate new stuff\nthat is brought in by this proposal.\n\n"}]}