Re: [PATCHv4] Documentation: triangular workflow

[Junio C Hamano <gitster@pobox.com>]

"Philip Oakley" <philipoakley@iee.org> writes:

> From: "Junio C Hamano" <gitster@pobox.com>
>> I do not think I agree.
>>
>> If you apriori know that you do want to hack on a project's code, then
>> forking at GitHub first and then cloning the copy would be OK.
>
> You've clipped my other point:
>
> -        One issue may be the different expectations of how the fork is
> -        created (it's only one click on the GitHub..)

Not really.  I said the same thing paraphrased:

    And at that point, you would create a publishing place, push into
    it, and tell others "Hey I did this interesting thing!".  That
    "create a publishing place" step could be just a one click at GitHub.

Anyway, let's step back a bit and agree that your local clone needs
to be told 4 pieces of information to help you in a triangular
workflow.  They are:

 * The URL of the "upstream";
 * The URL of the "publish" (aka "mine");
 * Your push should go to "publish" by default; and
 * Your pull should come from "upstream" by default.

Are we still on the same page, or have we already diverged?

If you start from a clone of "upstream", then the local clone
already knows two out of these four, namely, "The URL of the
'upstream' aka origin" and "Your pull should come from upstream by
default".  In order to go triangular, you still need to tell the
other two to your local clone, namely "There is another remote
called 'publish'" and "Your push should go to 'publish' not to
'origin'".

When you start by forking at GitHub and then cloning that fork,
would it make it easier to go triangular?  I do not think so.  The
local clone gives you (different) two out of these four, namely "The
URL of the 'publish' aka origin, which is your own fork" and "Your
push should go to 'publish'".  You still need to tell the other two,
"The URL of the 'upstream'" and "Your pull should come from
'upstream', not from 'origin'" to your local repository.

So I really do not see a point in arguing that "forking at GitHub is
easy with one click" favors "your local clone should start by
cloning your own fork".  Between starting from a clone of upstream
and starting from a clone of your own fork, it is the same amount of
work to go triangular even for people who fork before having any
clone locally, like you.

And I do not have to repeat myself that it is far more helpful to
give a recipe to go triangular starting from a clone of upstream for
people who first clone three similar projects to evaluate them,
discard two that do not suit their needs, and fork the best one, by
adding that fork as "publish" aka "mine", than giving a recipe to
start from a clone of one's own fork.

Having said that, there are indeed two interesting numbers we may
want to ask GitHub folks to help coming up with.  Take any popular
project with many public forks at GitHub, say rails with 13k forks.

 * How many "clone" from the upstream (i.e. rails/rails in this
   example) compared to 13k forks it has were made by the users?

   Many of them might be just following along (e.g. they want to
   build the tip of the tree that is ahead of any tagged released
   version), but there may be some among these local repositories
   cloned from upstream without forking that record their own
   commits.  These are the people who will benefit a version of the
   documentation under discussion if it describes how to start from
   a clone of upstream, then add your own fork as the publishing
   repository so that the user can use a triangular workflow.  I
   somehow suspect that there are a lot more than 13k (i.e. the
   number of public forks) of these people, but I do not think
   https://github.com/rails/rails page gives us the number.


 * What percentage of these 13k public forks are "empty forks",
   i.e. forked from the main project but has never been pushed into?

   It matters if the answer to this question is a non-trivial
   percentage.  It indicates that the owners of these forks did the
   "fork first and then clone from there", and had to do an extra
   work of adding the real upstream as another remote and set up to
   pull from there, if they wanted to just keep up to date; they
   would have been better off if they started by cloning the
   upstream first.