[PATCH] user-manual: remove temporary branch entry from todo list

[PATCH] user-manual: remove temporary branch entry from todo list

[Stephen P. Smith]

Remove the suggestion for using a detached HEAD instead of a
temporary branch.

Signed-off-by: Stephen P. Smith <ischis2@cox.net>
---

Notes:
    A search of the user manual found only one location which refers to
    temporary branches.  This has to do with how Tony Luck uses them.
    
    Even then there is a clarifying parenthetical noting that the
    temporary branches are topic branches.
    
    A git blame showed that the last time that the entry was updated was
    in 2007.

 Documentation/user-manual.txt | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c790ac..18e2f1e 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -4636,9 +4636,6 @@ Scan email archives for other stuff left out
 Scan man pages to see if any assume more background than this manual
 provides.
 
-Simplify beginning by suggesting disconnected head instead of
-temporary branch creation?
-
 Add more good examples.  Entire sections of just cookbook examples
 might be a good idea; maybe make an "advanced examples" section a
 standard end-of-chapter section?
-- 
2.7.0-rc2

Re: [PATCH] user-manual: remove temporary branch entry from todo list

[Junio C Hamano]

"Stephen P. Smith" <ischis2@cox.net> writes:

> Remove the suggestion for using a detached HEAD instead of a
> temporary branch.

That is something we can read from the patch text.  Please explain
why it is a good idea to remove it.

I can think of two completely different reasons:

 (1) Maybe the task was done some time ago, and we are seeing a
     stale todo item?

 (2) The task the todo item hints at was not done, but maybe it is
     not a good thing to do after all?

You seem to be hinting the former, but I do not think "the task was
done" is the case here.

> Signed-off-by: Stephen P. Smith <ischis2@cox.net>
> ---
>
> Notes:
>     A search of the user manual found only one location which refers to
>     temporary branches.  This has to do with how Tony Luck uses them.
>     
>     Even then there is a clarifying parenthetical noting that the
>     temporary branches are topic branches.
>     
>     A git blame showed that the last time that the entry was updated was
>     in 2007.
>
>  Documentation/user-manual.txt | 3 ---
>  1 file changed, 3 deletions(-)
>
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 1c790ac..18e2f1e 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -4636,9 +4636,6 @@ Scan email archives for other stuff left out
>  Scan man pages to see if any assume more background than this manual
>  provides.
>  
> -Simplify beginning by suggesting disconnected head instead of
> -temporary branch creation?
> -

What does "beginning" refer to in this sentence, though?

After a quick reading of the beginning part of the document, I am
getting the impression that it refers to the use of the 'new'
branch, which is initially created out of v2.6.13 and then later
reset to v2.6.17 while the user is in the sightseeing mode.  And
this way of working _is_ a remnant from the days back when detached
HEAD was not with us.

It is a completely separate matter if it is a good idea to teach
detached HEAD that early in the tutorial, though.  So "remove the
task because detached HEAD is a bit too weird thing to learn in that
early stage in the learning curve" (i.e. the latter reason) might
apply.

Re: [PATCH] user-manual: remove temporary branch entry from todo list

[Stephen & Linda Smith]

On Sunday, December 27, 2015 06:41:09 PM Junio C Hamano wrote:
> "Stephen P. Smith" <ischis2@cox.net> writes:
> 
> > Remove the suggestion for using a detached HEAD instead of a
> > temporary branch.
> 
> That is something we can read from the patch text.  Please explain
> why it is a good idea to remove it.
> 
> I can think of two completely different reasons:
> 
>  (1) Maybe the task was done some time ago, and we are seeing a
>      stale todo item?
> 
>  (2) The task the todo item hints at was not done, but maybe it is
>      not a good thing to do after all?
> 
> You seem to be hinting the former, but I do not think "the task was
> done" is the case here.
 
I think that this is a stale todo.   
 
The only place there is a mention of temporary branches (which 
is then parenthetically called a topic branch) is in relation to how Tony Luck organizes his work.   
Additionally there is already a subsection on using a detatched head ("Examining an 
old version without creating a new branch). 
 
If there is more that was wanted, then I would be glad to add something, but 
I don't see that there are references to remove.
 
> 
> > Signed-off-by: Stephen P. Smith <ischis2@cox.net>
> > ---
> >
> > Notes:
> >     A search of the user manual found only one location which refers to
> >     temporary branches.  This has to do with how Tony Luck uses them.
> >     
> >     Even then there is a clarifying parenthetical noting that the
> >     temporary branches are topic branches.
> >     
> >     A git blame showed that the last time that the entry was updated was
> >     in 2007.
> >
> >  Documentation/user-manual.txt | 3 ---
> >  1 file changed, 3 deletions(-)
> >
> > diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> > index 1c790ac..18e2f1e 100644
> > --- a/Documentation/user-manual.txt
> > +++ b/Documentation/user-manual.txt
> > @@ -4636,9 +4636,6 @@ Scan email archives for other stuff left out
> >  Scan man pages to see if any assume more background than this manual
> >  provides.
> >  
> > -Simplify beginning by suggesting disconnected head instead of
> > -temporary branch creation?
> > -
> 
> What does "beginning" refer to in this sentence, though?

I had that question too even after looking at the 2007 version of the manual.

> 
> After a quick reading of the beginning part of the document, I am
> getting the impression that it refers to the use of the 'new'
> branch, which is initially created out of v2.6.13 and then later
> reset to v2.6.17 while the user is in the sightseeing mode.  And
> this way of working _is_ a remnant from the days back when detached
> HEAD was not with us.
> 
> It is a completely separate matter if it is a good idea to teach
> detached HEAD that early in the tutorial, though.  
 
So are you suggesting a move of the section further down?   
Or are you suggesting that that is excised from the manual?

> So "remove the task because detached HEAD is a bit too weird thing to learn in that
> early stage in the learning curve" (i.e. the latter reason) might
> apply.
 
Could it be there are two reasons to remove the todo?

> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] user-manual: remove temporary branch entry from todo list

[Junio C Hamano]

Stephen & Linda Smith <ischis2@cox.net> writes:

> I think that this is a stale todo.   
>  
> The only place there is a mention of temporary branches (which is
> then parenthetically called a topic branch) is in relation to how
> Tony Luck organizes his work.  Additionally there is already a
> subsection on using a detatched head ("Examining an old version
> without creating a new branch).

I suspect that you stared at the output from "git grep" for
"temporary" or even "temporary branch" and further I suspect that
the experience blinded you.

The two lines in that todo item were first introduced at d5cd5de4
(Documentation: begin discussion of git-remote in user manual,
2007-01-09), and then were updated at b181d57f (user-manual:
reorganize fetch discussion, add internals, etc., 2007-01-27).  In
between these two, the lines were rewrapped at 2f99710c
(user-manual: rewrap, fix heading levels, 2007-01-14) but that
commit was purely cosmetic.

When the todo item was introduced, it ended with a full-stop; the
update changed it to a question mark, which I read it as hinting
that the item might not be a good change.

The output from

    $ git diff -U40 d5cd5de4 b181d57f Documentation/user-manual.txt

gives us a fairly good answer.  When the todo item was introduced,
the "beginning" section was titled "Repositories and Branches", and
showed you how to clone the Linux kernel in its first subsection,
and then the next subsection showed "How to check out a different
version", and showed that "git checkout -b new v2.6.13", followed by
"git reset --hard v2.6.17", are the commands to use for sightseeing
the project's landmarks.

The "new" is used as a temporary branch in the context of that
example; the user is not building anything on top of these commits,
the use of a named branch is ephemeral and the only reason a named
branch is used is because the detached HEAD was a fairly new
invention, introduced at c847f537 (Detached HEAD (experimental),
2007-01-01) and was merged to the mainline at c388761c (Merge branch
'jc/detached-head', 2007-01-11).

After commit b181d57f, aka "Let's keep the todo item for now, but I
am no longer sure if it is a good idea so end it with a question
mark", the "beginning" is a new section called "Git Quick Start",
but the same "git checkout -b new v2.6.15" for sightseeing appears
in this new section.

Another thing to notice is that the "temporary branch" you found in
"git grep" about Tony's workflow did not exist in the user-manual
back in these days.  It was added to the user-manual at 9e2163ea
(user-manual: move howto/using-topic-branches into manual,
2007-05-13), so the todo item couldn't possibly have been referring
to that example.

>> > -Simplify beginning by suggesting disconnected head instead of
>> > -temporary branch creation?
>> > -
>> 
>> What does "beginning" refer to in this sentence, though?
>
> I had that question too even after looking at the 2007 version of the manual.
>> 
>> After a quick reading of the beginning part of the document, I am
>> getting the impression that it refers to the use of the 'new'
>> branch, which is initially created out of v2.6.13 and then later
>> reset to v2.6.17 while the user is in the sightseeing mode.  And
>> this way of working _is_ a remnant from the days back when detached
>> HEAD was not with us.
>> 
>> It is a completely separate matter if it is a good idea to teach
>> detached HEAD that early in the tutorial, though.  
>  
> So are you suggesting a move of the section further down?   
> Or are you suggesting that that is excised from the manual?

Neither.  Because the current text does not teach detached HEAD
early in the tutorial, I see no need to move any section down, or
excising a section.

>> So "remove the task because detached HEAD is a bit too weird
>> thing to learn in that early stage in the learning curve"
>> (i.e. the latter reason) might apply.
>  
> Could it be there are two reasons to remove the todo?

There could be, but I do not think it is the case here.

I do not think "it was already done" is a valid reason for removing
this todo item, as I do not think it was done yet.

I think the only possible reason to remove that todo item is because
teaching detached HEAD that early in the user manual gives a bit too
steep learning curve--and I do not disagree with that justification.

[PATCH V2] user-manual: remove temporary branch entry from todo list

[Stephen P. Smith]

In the section on "How to check out a differnet version of a project"
the "new" branch is used as a temporary branch.

A detached HEAD was not used since it was a new feature introduced
just a couple weeks prior.

The section could be changed to use and explain a detached HEAD,
except that would increase the learning curve early in the manual.

Detached HEADs are discussed a couple sections later under
"Examining an old version without creating a new branch".

Signed-off-by: Stephen P. Smith <ischis2@cox.net>
---
 Documentation/user-manual.txt | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 1c790ac..18e2f1e 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -4636,9 +4636,6 @@ Scan email archives for other stuff left out
 Scan man pages to see if any assume more background than this manual
 provides.
 
-Simplify beginning by suggesting disconnected head instead of
-temporary branch creation?
-
 Add more good examples.  Entire sections of just cookbook examples
 might be a good idea; maybe make an "advanced examples" section a
 standard end-of-chapter section?
-- 
2.7.0-rc2

Re: [PATCH] user-manual: remove temporary branch entry from todo list

[Stephen & Linda Smith]

On Monday, December 28, 2015 09:29:13 AM Junio C Hamano wrote:
> Stephen & Linda Smith <ischis2@cox.net> writes:
> 
> > I think that this is a stale todo.   
> >  
> > The only place there is a mention of temporary branches (which is
> > then parenthetically called a topic branch) is in relation to how
> > Tony Luck organizes his work.  Additionally there is already a
> > subsection on using a detatched head ("Examining an old version
> > without creating a new branch).
> 
> I suspect that you stared at the output from "git grep" for
> "temporary" or even "temporary branch" and further I suspect that
> the experience blinded you.
> 
> The two lines in that todo item were first introduced at d5cd5de4
> (Documentation: begin discussion of git-remote in user manual,
> 2007-01-09), and then were updated at b181d57f (user-manual:
> reorganize fetch discussion, add internals, etc., 2007-01-27).  In
> between these two, the lines were rewrapped at 2f99710c
> (user-manual: rewrap, fix heading levels, 2007-01-14) but that
> commit was purely cosmetic.
> 
> When the todo item was introduced, it ended with a full-stop; the
> update changed it to a question mark, which I read it as hinting
> that the item might not be a good change.
> 
> The output from
> 
>     $ git diff -U40 d5cd5de4 b181d57f Documentation/user-manual.txt
> 
> gives us a fairly good answer.  When the todo item was introduced,
> the "beginning" section was titled "Repositories and Branches", and
> showed you how to clone the Linux kernel in its first subsection,
> and then the next subsection showed "How to check out a different
> version", and showed that "git checkout -b new v2.6.13", followed by
> "git reset --hard v2.6.17", are the commands to use for sightseeing
> the project's landmarks.
> 
> The "new" is used as a temporary branch in the context of that
> example; the user is not building anything on top of these commits,
> the use of a named branch is ephemeral and the only reason a named
> branch is used is because the detached HEAD was a fairly new
> invention, introduced at c847f537 (Detached HEAD (experimental),
> 2007-01-01) and was merged to the mainline at c388761c (Merge branch
> 'jc/detached-head', 2007-01-11).
> 
> After commit b181d57f, aka "Let's keep the todo item for now, but I
> am no longer sure if it is a good idea so end it with a question
> mark", the "beginning" is a new section called "Git Quick Start",
> but the same "git checkout -b new v2.6.15" for sightseeing appears
> in this new section.
> 
> Another thing to notice is that the "temporary branch" you found in
> "git grep" about Tony's workflow did not exist in the user-manual
> back in these days.  It was added to the user-manual at 9e2163ea
> (user-manual: move howto/using-topic-branches into manual,
> 2007-05-13), so the todo item couldn't possibly have been referring
> to that example.
> 
> >> > -Simplify beginning by suggesting disconnected head instead of
> >> > -temporary branch creation?
> >> > -
> >> 
> >> What does "beginning" refer to in this sentence, though?
> >
> > I had that question too even after looking at the 2007 version of the manual.
> >> 
> >> After a quick reading of the beginning part of the document, I am
> >> getting the impression that it refers to the use of the 'new'
> >> branch, which is initially created out of v2.6.13 and then later
> >> reset to v2.6.17 while the user is in the sightseeing mode.  And
> >> this way of working _is_ a remnant from the days back when detached
> >> HEAD was not with us.
> >> 
> >> It is a completely separate matter if it is a good idea to teach
> >> detached HEAD that early in the tutorial, though.  
> >  
> > So are you suggesting a move of the section further down?   
> > Or are you suggesting that that is excised from the manual?
> 
> Neither.  Because the current text does not teach detached HEAD
> early in the tutorial, I see no need to move any section down, or
> excising a section.
> 
> >> So "remove the task because detached HEAD is a bit too weird
> >> thing to learn in that early stage in the learning curve"
> >> (i.e. the latter reason) might apply.
> >  
> > Could it be there are two reasons to remove the todo?
> 
> There could be, but I do not think it is the case here.
> 
> I do not think "it was already done" is a valid reason for removing
> this todo item, as I do not think it was done yet.
> 
> I think the only possible reason to remove that todo item is because
> teaching detached HEAD that early in the user manual gives a bit too
> steep learning curve--and I do not disagree with that justification.

I will rework the patch using the above analysis in the commit message.   Of
course I will rewrite for readability.

Re: [PATCH] user-manual: remove temporary branch entry from todo list

[Junio C Hamano]

Stephen & Linda Smith <ischis2@cox.net> writes:

> I will rework the patch using the above analysis in the commit message.   Of
> course I will rewrite for readability.

Thanks.  Will apply.