Update FAQ_DEV.

1 files changed, 104 insertions, 4 deletions

diff --git a/doc/FAQ_DEV b/doc/FAQ_DEV
index 71439a22e33..9055d38fa78 100644
--- a/doc/FAQ_DEV
+++ b/doc/FAQ_DEV
@@ -29,6 +29,7 @@
    13) What is CommandCounterIncrement()?
    14) Why don't we use threads in the backend?
    15) How are RPM's packaged?
+   16) How are CVS branches handled?
      _________________________________________________________________
    
   1) What tools are available for developers?
@@ -36,18 +37,18 @@
    Aside from the User documentation mentioned in the regular FAQ, there
    are several development tools available. First, all the files in the
    /tools directory are designed for developers.
-    RELEASE_CHANGES     changes we have to make for each release
-    SQL_keywords        standard SQL'92 keywords
+    RELEASE_CHANGES changes we have to make for each release
+    SQL_keywords    standard SQL'92 keywords
     backend         description/flowchart of the backend directories
     ccsym           find standard defines made by your compiler
     entab           converts tabs to spaces, used by pgindent
     find_static     finds functions that could be made static
-    find_typedef    finds a list of typedefs in the source code
+    find_typedef    finds typedefs in the source code
     find_badmacros  finds macros that use braces incorrectly
     make_ctags      make vi 'tags' file in each directory
     make_diff       make *.orig and diffs of source
     make_etags      make emacs 'etags' files
-    make_keywords.README    make comparison of our keywords and SQL'92
+    make_keywords   make comparison of our keywords and SQL'92
     make_mkid       make mkid ID files
     mkldexport      create AIX exports file
     pgindent        indents C source files
@@ -530,3 +531,102 @@ stance. IMHO, of course.
 
 Of course, there are many projects that DO include all the files
 necessary to build RPMs from their Official Tarball (TM).
+
+  16) How are CVS branches managed?
+  
+   This was written by Tom Lane:
+If you just do basic "cvs checkout", "cvs update", "cvs commit", then
+you'll always be dealing with the HEAD version of the files in CVS.
+That's what you want for development, but if you need to patch past
+stable releases then you have to be able to access and update the
+"branch" portions of our CVS repository.  We normally fork off a branch
+for a stable release just before starting the development cycle for the
+next release.
+
+The first thing you have to know is the branch name for the branch you
+are interested in getting at.  Unfortunately Marc has been less than
+100% consistent in naming the things.  One way to check is to apply
+"cvs log" to any file that goes back a long time, for example HISTORY
+in the top directory:
+
+$ cvs log HISTORY | more
+
+RCS file: /home/projects/pgsql/cvsroot/pgsql/HISTORY,v
+Working file: HISTORY
+head: 1.106
+branch:
+locks: strict
+access list:
+symbolic names:
+        REL7_1_STABLE: 1.106.0.2
+        REL7_1_BETA: 1.79
+        REL7_1_BETA3: 1.86
+        REL7_1_BETA2: 1.86
+        REL7_1: 1.102
+        REL7_0_PATCHES: 1.70.0.2
+        REL7_0: 1.70
+        REL6_5_PATCHES: 1.52.0.2
+        REL6_5: 1.52
+        REL6_4: 1.44.0.2
+        release-6-3: 1.33
+        SUPPORT: 1.1.1.1
+        PG95-DIST: 1.1.1
+keyword substitution: kv
+total revisions: 129;   selected revisions: 129
+More---q
+
+Unfortunately "cvs log" isn't all that great about distinguishing
+branches from tags --- it calls 'em all "symbolic names".  (A "tag" just
+marks a specific timepoint across all files --- it's essentially a
+snapshot whereas a branch is a changeable fileset.)  Rule of thumb is
+that names attached to four-number versions where the third number is
+zero represent branches, the others are just tags.  Here we can see that
+the extant branches are
+        REL7_1_STABLE
+        REL7_0_PATCHES
+        REL6_5_PATCHES
+The next commit to the head will be revision 1.107, whereas any changes
+committed into the REL7_1_STABLE branch will have revision numbers like
+1.106.2.*, corresponding to the branch number 1.106.0.2 (don't ask where
+the zero went...).
+
+OK, so how do you do work on a branch?  By far the best way is to create
+a separate checkout tree for the branch and do your work in that.  Not
+only is that the easiest way to deal with CVS, but you really need to
+have the whole past tree available anyway to test your work.  (And you
+*better* test your work.  Never forget that dot-releases tend to go out
+with very little beta testing --- so whenever you commit an update to a
+stable branch, you'd better be doubly sure that it's correct.)
+
+Normally, to checkout the head branch, you just cd to the place you
+want to contain the toplevel "pgsql" directory and say
+
+        cvs ... checkout pgsql
+
+To get a past branch, you cd to whereever you want it and say
+
+        cvs ... checkout -r BRANCHNAME pgsql
+
+For example, just a couple days ago I did
+
+        mkdir ~postgres/REL7_1
+        cd ~postgres/REL7_1
+        cvs ... checkout -r REL7_1_STABLE pgsql
+
+and now I have a maintenance copy of 7.1.*.
+
+When you've done a checkout in this way, the branch name is "sticky":
+CVS automatically knows that this directory tree is for the branch,
+and whenever you do "cvs update" or "cvs commit" in this tree, you'll
+fetch or store the latest version in the branch, not the head version.
+Easy as can be.
+
+So, if you have a patch that needs to apply to both the head and a
+recent stable branch, you have to make the edits and do the commit
+twice, once in your development tree and once in your stable branch
+tree.  This is kind of a pain, which is why we don't normally fork
+the tree right away after a major release --- we wait for a dot-release
+or two, so that we won't have to double-patch the first wave of fixes.
+
+   Also, Ian Lance Taylor points out that branches and tags can be
+   distiguished by using "cvs status -v".