changes in r112843

changes in r112843

[Glenn Morris]

   *** doc/emacs/maintaining.texi  2013-05-30 09:27:55 +0000
   --- doc/emacs/maintaining.texi  2013-06-02 11:56:39 +0000
   ***************
   *** 1266,1275 ****
     @cindex branch (version control)
     
       One use of version control is to support multiple independent lines
   ! of development, which are called @dfn{branches}.  Branches are used
   ! for maintaining separate ``stable'' and ``development'' versions of a
   ! program, and for developing unrelated features in isolation from one
   ! another.
     
       VC's support for branch operations is currently fairly limited.  For
     decentralized version control systems, it provides commands for
   --- 1267,1282 ----
     @cindex branch (version control)
     
       One use of version control is to support multiple independent lines
   ! of development, which are called @dfn{branches}.  Branches allow for
   ! parts of software to be developed in parallel.  Large projects require
   ! many roles to be filled, including developers, build managers, and
   ! quality assurance personnel. Further, multiple releases on different
   ! operating system platforms may have to be maintained.  Branches allow
   ! contributors to isolate changes without destabilizing the codebase,
   ! for example, fixes for bugs, new features, and versions
   ! integration. These changes may be later merged (resynchronized) after
   ! testing.


The new text is copied verbatim from Wikipedia.
Please just remove it, since (IMO) the Emacs manual does not need to
explain every possible reason why people might want to use branches.

Re: changes in r112843

[Xue Fuqiao]

On Wed, Jun 5, 2013 at 1:40 AM, Glenn Morris <rgm@gnu.org> wrote:
>
>    *** doc/emacs/maintaining.texi  2013-05-30 09:27:55 +0000
>    --- doc/emacs/maintaining.texi  2013-06-02 11:56:39 +0000
>    ***************
>    *** 1266,1275 ****
>      @cindex branch (version control)
>
>        One use of version control is to support multiple independent lines
>    ! of development, which are called @dfn{branches}.  Branches are used
>    ! for maintaining separate ``stable'' and ``development'' versions of a
>    ! program, and for developing unrelated features in isolation from one
>    ! another.
>
>        VC's support for branch operations is currently fairly limited.  For
>      decentralized version control systems, it provides commands for
>    --- 1267,1282 ----
>      @cindex branch (version control)
>
>        One use of version control is to support multiple independent lines
>    ! of development, which are called @dfn{branches}.  Branches allow for
>    ! parts of software to be developed in parallel.  Large projects require
>    ! many roles to be filled, including developers, build managers, and
>    ! quality assurance personnel. Further, multiple releases on different
>    ! operating system platforms may have to be maintained.  Branches allow
>    ! contributors to isolate changes without destabilizing the codebase,
>    ! for example, fixes for bugs, new features, and versions
>    ! integration. These changes may be later merged (resynchronized) after
>    ! testing.

> The new text is copied verbatim from Wikipedia.
> Please just remove it, since (IMO) the Emacs manual does not need to
> explain every possible reason why people might want to use branches.

IMHO (at least) this sentence is useful here:

  Branches allow contributors to isolate changes without destabilizing the
  codebase, for example, fixes for bugs, new features, and
  versions integration.

--
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: changes in r112843

[Xue Fuqiao]

On Wed, Jun 5, 2013 at 6:59 AM, Xue Fuqiao <xfq.free@gmail.com> wrote:
> On Wed, Jun 5, 2013 at 1:40 AM, Glenn Morris <rgm@gnu.org> wrote:
>>
>>    *** doc/emacs/maintaining.texi  2013-05-30 09:27:55 +0000
>>    --- doc/emacs/maintaining.texi  2013-06-02 11:56:39 +0000
>>    ***************
>>    *** 1266,1275 ****
>>      @cindex branch (version control)
>>
>>        One use of version control is to support multiple independent lines
>>    ! of development, which are called @dfn{branches}.  Branches are used
>>    ! for maintaining separate ``stable'' and ``development'' versions of a
>>    ! program, and for developing unrelated features in isolation from one
>>    ! another.
>>
>>        VC's support for branch operations is currently fairly limited.  For
>>      decentralized version control systems, it provides commands for
>>    --- 1267,1282 ----
>>      @cindex branch (version control)
>>
>>        One use of version control is to support multiple independent lines
>>    ! of development, which are called @dfn{branches}.  Branches allow for
>>    ! parts of software to be developed in parallel.  Large projects require
>>    ! many roles to be filled, including developers, build managers, and
>>    ! quality assurance personnel. Further, multiple releases on different
>>    ! operating system platforms may have to be maintained.  Branches allow
>>    ! contributors to isolate changes without destabilizing the codebase,
>>    ! for example, fixes for bugs, new features, and versions
>>    ! integration. These changes may be later merged (resynchronized) after
>>    ! testing.
>
>> The new text is copied verbatim from Wikipedia.
>> Please just remove it, since (IMO) the Emacs manual does not need to
>> explain every possible reason why people might want to use branches.
>
> IMHO (at least) this sentence is useful here:
>
>   Branches allow contributors to isolate changes without destabilizing the
>   codebase, for example, fixes for bugs, new features, and
>   versions integration.

Or just only leave the first sentence:
  One use of version control is to support multiple independent lines.

Remove the (both versions) motivation of branching.

--
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: changes in r112843

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 866 bytes --]

() Xue Fuqiao <xfq.free@gmail.com>
() Wed, 5 Jun 2013 07:12:24 +0800

   Remove the (both versions) motivation of branching.

I think most who read this part of the manual will already have
notions of branching as they pertain to their favorite VCS.
Probably what they seek (what we should provide here) is the
assurance that Emacs can be congruent to that particular model,
amongst others.

IOW, in "branch on a tree" the key word in this context is "on".

How about removing motivation and adding in its place text that
qualifies "independent lines" w/ the notion of a (possibly) shared
base (point of intersection) for these lines?  I say "possibly"
because VCS support for multiple roots (full independence) is not
universal, and anyway in practice full independence is almost
entirely undesirable.

-- 
Thien-Thi Nguyen
GPG key: 4C807502

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: changes in r112843

[Xue Fuqiao]

On Wed, Jun 5, 2013 at 6:46 PM, Thien-Thi Nguyen <ttn@gnu.org> wrote:
> () Xue Fuqiao <xfq.free@gmail.com>
> () Wed, 5 Jun 2013 07:12:24 +0800
>
>    Remove the (both versions) motivation of branching.
>
> I think most who read this part of the manual will already have
> notions of branching as they pertain to their favorite VCS.
> Probably what they seek (what we should provide here) is the
> assurance that Emacs can be congruent to that particular model,
> amongst others.
>
> IOW, in "branch on a tree" the key word in this context is "on".

1+

> How about removing motivation and adding in its place text that
> qualifies "independent lines" w/ the notion of a (possibly) shared
> base (point of intersection) for these lines?  I say "possibly"
> because VCS support for multiple roots (full independence) is not
> universal, and anyway in practice full independence is almost
> entirely undesirable.

Looks good.  Would you like to send a patch here (or install it yourself
if you think it's appropriate)?  I'm not confident in my phrasing.

--
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/

Re: changes in r112843

[Thien-Thi Nguyen]

[-- Attachment #1: Type: text/plain, Size: 583 bytes --]

() Xue Fuqiao <xfq.free@gmail.com>
() Thu, 6 Jun 2013 07:13:33 +0800

   > How about removing motivation and adding in its place text that
   > [describes branch points]

   Looks good.  Would you like to send a patch here (or install it
   yourself if you think it's appropriate)?  I'm not confident in my
   phrasing.

No, thanks.  I would prefer you to take heart and push through the
change (to) yourself, so that you control the iteration and tempo.
That is how to gain phrased wor[dk]s by doing phrased reflection.  :-D

-- 
Thien-Thi Nguyen
GPG key: 4C807502

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: changes in r112843

[Glenn Morris]

First, thank you for trying to improve the Emacs documentation.

My main point was, please don't copy text from other sources (especially
without attribution). Instead, it is much better to add a
cross-reference. This avoids duplication, and helps keep the size of the
manual down. (Or find your own phrasing. If you are not confident that
you have it correct, there are lots of people on this list who love
critiquing grammar etc.)

In this case, it would be something like: for more information on
branches, see <url:wikipedia/branches>. Which IMO shows how pointless it
is, because such a note could be added after just about every word in
the manual. It's obvious, and we don't need to state the obvious.

The Emacs manual does not need to explain why to use branches. It just
needs to say; if you _are_ using branches, here is how Emacs can help.
To avoid anyone reading the Emacs manual who doesn't know what a branch
is getting totally confused, there can optionally be a brief explanatory
sentence. That is what the original text had. Of course we could quibble
about the precise wording all day, but doing so won't improve the Emacs
manual measurably.