[Gnu-arch-users] More Doc changes

[Pierce T . Wetter III]

 Ok, thanks for the feedback to the last go round, here's the next 
rough patch for me:


 Understanding categories, branches, versions, and revisions

 By specifying the category, branch, version, and revision to tla, you 
are describing a particular set of source, and a particular state of 
that source.


 Categories:

   The category name is purely organizational, and specifies the start 
of a
   source history tree in arch.  While
   this can correspond to a single development project, like in this 
tutorial, it
   can also correspond to a collection of projects. A large development 
team
   might have separate categories for tools vs. libraries for instance. 
Categories
   let you group related source together as a unit.

   Category names are pretty much up to you.

   Examples:

      customer1       (source code for a customer)
      gnugo           (source code for a particular project)
      projects        (source code for all projects)
      work            (source code for work)
      play            (source code for play)
      vendor-tla      (source code for a tool from a particular vendor)

 Branches:

   Branches are variations on a set of related source, so they are the 
first
   level of "state" in a set of source. While arch supports as many
   branches as you like, in practice most people's work process is that 
there is
   a "mainline" where most development happens. Occasionally, a 
developer or
   developers will need to work on a code change over a long period of 
time, while
   keeping the main source viable. Branches allow these sorts of 
"detours" to
   occur.

   Branches can also allow parallel development. A common example of 
this is where
   you "feature freeze" for a release, which means that you really end 
up having
   to fix bugs in both the development and release tracks.

   Branches can be named however you like, "mainline" and "trunk" are 
somewhat
   standard names for the main line of development.

  Examples:

     main
     mainline
     trunk
     development            (names you might use for the main 
development line)

     release1.0
     deployment             (names you might use when you "code freeze" 
for a
                             release)

 Versions:

   Does anyone actually use these for anything? What purpose do they 
serve?

LONG ASIDE BEGINS:
   My guess: version numbers give you another degree of freedom beyond 
a branch,
   so that you can have:

      project--main--1.0
      project--main--2.0

    Without having to have something like "main1.0" as the branch name. 
In
    practice, they work the same as making a branch, but it recognizes 
the release
    process as part of the development cycle. So you could have a 
"release" script
    that would tie off the current set of changes, increment the old 
version
    number, and start what's basically a new branch.

    It probably makes the most sense for the main line, because:

     project--complicated-bug-fix--0.1

     could actually have been a branch from either:

      project--main--1.0
      project--main--2.0

     above, and the above name doesn't make it clear. If version 
numbers came
     first:

      project--2.0--complicated-bug-fix

     Then that would imply that complicated-bug-fix is a branch off of

      project--2.0--main

     So anyways, either version numbers auto increment in some way I 
don't
     know about yet, or they're just kind of there, and no one uses them
     unless they have formal releases.

LONG ASIDE ENDS:


 Revisions:

   This is literally the number of patches that need to be applied from 
the
   starting source set to get that revision.

   Examples:

     base-0                (no patches needed)
     patch-1               (1 patch needed)
     patch-99              (patches 1-99 needed)

  (aside: should patch-0 be a synonym for base-0 to make scripting 
easier)

  Why all this folderol:

    Source code in active development is a collection of streams of 
changes. So in order to specify a specific state of the code base, you 
need to specify which code collectino, which stream of that code code 
collection, and what moment in time you wish to access of that 
tributary.