Rewrite portions of development.7 to make sense

in the world of subversion.

Approved by:	gjb
MFC after:	2 weeks

1 files changed, 41 insertions, 250 deletions

diff --git a/share/man/man7/development.7 b/share/man/man7/development.7
index ea7df38..1f25871 100644
--- a/share/man/man7/development.7
+++ b/share/man/man7/development.7
@@ -23,7 +23,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 2, 2012
+.Dd September 19, 2012
 .Dt DEVELOPMENT 7
 .Os
 .Sh NAME
@@ -48,7 +48,7 @@ kernel.
 The methods described
 here are as applicable to production installations as it is to development
 environments.
-You need a good 12-17GB of disk space on one machine to make this work
+You need approximately 10GB of disk space on one machine to make this work
 conveniently.
 .Sh SETTING UP THE ENVIRONMENT ON THE MASTER SERVER
 Your master server should always run a stable, production version of the
@@ -62,9 +62,9 @@ where you lose the environment and/or cannot recover from a mistake.
 .Pp
 Create a huge partition called
 .Pa /FreeBSD .
-8-12GB is recommended.
+Approximately 7GB is recommended.
 This partition will contain nearly all the development environment,
-including the CVS tree, broken-out source, and possibly even object files.
+including the subversion tree, broken-out source, and possibly even object files.
 You are going to export this partition to your other machines via a
 READ-ONLY NFS export so do not mix it with other more security-sensitive
 partitions.
@@ -89,70 +89,19 @@ I recommend a
 partition of at least 5GB.
 .Pp
 On the master server, use
-.Xr csup 1
-to automatically pull down and maintain
+.Xr svn 1
+to pull down and maintain
 the
 .Fx
-CVS archive once a day.
+source.
 The first pull will take a long time,
 it is several gigabytes, but once you have it,
-the daily synchronizations will be quite small.
-.Bd -literal -offset 4n
-mkdir /FreeBSD/FreeBSD-CVS
-rm -rf /home/ncvs
-ln -s /FreeBSD/FreeBSD-CVS /home/ncvs
-.Ed
-.Pp
-The
-.Xr cron 8
-job should look something like this (please randomize the time of
-day!).
-Note that you can use the
-.Xr csup 1
-configuration file example directly from
-.Pa /usr/share/examples
-without modification by supplying appropriate arguments
-to
-.Xr csup 1 .
-.Bd -literal -offset 4n
-33 6 * * *      /usr/bin/csup -r 20 -L 2 -h cvsup.freebsd.org /usr/share/examples/cvsup/cvs-supfile
-.Ed
-.Pp
-Run the
-.Xr csup 1
-manually the first time to pull down the archive.
-It could take
-all day depending on how fast your connection is!
-You will run all
-.Xr csup 1
-and
-.Xr cvs 1
+the updates will be quite small.
+Run all
+.Xr svn 1
 operations as
 .Dq Li root
-and you need to set up a
-.Pa ~/.cvsrc
-.Pq Pa /root/.cvsrc
-file, as shown below, for proper
-.Xr cvs 1
-operation.
-Using
-.Pa ~/.cvsrc
-to specify
-.Xr cvs 1
-defaults is an excellent way to
-.Dq "file and forget" ,
-but you should never forget that you put them in there.
-.Bd -literal -offset 4n
-# cvs -q
-diff -u
-update -Pd
-checkout -P
-.Ed
 .Pp
-Now use
-.Xr cvs 1
-to check out a -STABLE source tree and a -CURRENT source tree,
-as well as ports and docs, to create your initial source environment.
 Keeping the broken-out source and ports in
 .Pa /FreeBSD
 allows you to export
@@ -160,71 +109,16 @@ it to other machines via read-only NFS.
 This also means you only need to edit/maintain files in one place and all
 your clients automatically pick up the changes.
 .Bd -literal -offset 4n
-mkdir /FreeBSD/FreeBSD-4.x
-mkdir /FreeBSD/FreeBSD-current
-
-cd /FreeBSD/FreeBSD-4.x
-cvs -d /home/ncvs checkout -rRELENG_4 src
-
-cd /FreeBSD/FreeBSD-current
-cvs -d /home/ncvs checkout src
-cvs -d /home/ncvs checkout ports
-cvs -d /home/ncvs checkout doc
-.Ed
-.Pp
-Now create a softlink for
-.Pa /usr/src
-and
-.Pa /usr/src2 .
-On the main server I always point
-.Pa /usr/src
-at -STABLE and
-.Pa /usr/src2
-at -CURRENT.
-On client machines I usually do not have a
-.Pa /usr/src2
-and I make
-.Pa /usr/src
-point at whatever version of
-.Fx
-the client box is intended to
-run.
-.Bd -literal -offset 4n
-cd /usr
-rm -rf src src2
-ln -s /FreeBSD/FreeBSD-4.x/src src	(could be -CURRENT on a client)
-ln -s /FreeBSD/FreeBSD-current/src src2	(MASTER SERVER ONLY)
-.Ed
-.Pp
-Now you have to make a choice for
-.Pa /usr/obj .
-Well, hopefully you made it already and chose the partition method.
-If you
-chose poorly you probably intend to put it in
-.Pa /FreeBSD
-and, if so, this is
-what you want to do:
-.Bd -literal -offset 4n
-(ONLY IF YOU MADE A POOR CHOICE AND PUT /usr/obj in /FreeBSD!)
-mkdir /FreeBSD/obj
+mkdir /FreeBSD
+cd /FreeBSD
+svn co svn://svn.freebsd.org/ports/head ports
+svn co svn://svn.freebsd.org/doc/head doc
+svn co svn://svn.freebsd.org/base/head src
 cd /usr
-rm -rf obj
-ln -s /FreeBSD/obj obj
+rm -rf src
+ln -s /FreeBSD/src src
 .Ed
 .Pp
-Alternatively you may chose simply to leave
-.Pa /usr/obj
-in
-.Pa /usr .
-If your
-.Pa /usr
-is large enough this will work, but I do not recommend it for
-safety reasons
-.Pa ( /usr/obj
-is constantly being modified,
-.Pa /usr
-is not).
-.Pp
 Note that exporting
 .Pa /usr/obj
 via read-only NFS to your other boxes will
@@ -240,19 +134,17 @@ problems and issues down the line and presents a security problem as well.
 It is far easier to do builds on the master server and then only do installs
 on the clients.
 .Pp
-I usually maintain my ports tree via CVS.
-It is sitting right there in the master CVS archive and I have even told you
-to check it out (see above).
+I usually maintain my ports tree via svn or portsnap.
 With some fancy softlinks you can make the ports tree available both on your
 master server and on all of your other machines.
-Note that the ports tree exists only on the HEAD CVS branch, so its always
--CURRENT even on a -STABLE box.
+Note that the ports tree exists only on the HEAD ports branch, so its always
+usable even on a -STABLE box.
 This is what you do:
 .Bd -literal -offset 4n
 (THESE COMMANDS ON THE MASTER SERVER AND ON ALL CLIENTS)
 cd /usr
 rm -rf ports
-ln -s /FreeBSD/FreeBSD-current/ports ports
+ln -s /FreeBSD/ports ports
 
 cd /usr/ports   			(this pushes into the softlink)
 rm -rf distfiles			(ON MASTER SERVER ONLY)
@@ -344,7 +236,7 @@ into the NFS-mounted environment.
 If a particular client is running -CURRENT,
 .Pa /usr/src
 should be a softlink to
-.Pa /FreeBSD/FreeBSD-current/src .
+.Pa /FreeBSD/src .
 If it is running -STABLE,
 .Pa /usr/src
 should be a softlink to
@@ -359,8 +251,8 @@ human variety) on a client.
 (ON EACH CLIENT)
 cd /usr
 rm -rf ports src
-ln -s /FreeBSD/FreeBSD-current/ports ports
-ln -s /FreeBSD/FreeBSD-XXX/src src
+ln -s /FreeBSD/ports ports
+ln -s /FreeBSD/src src
 .Ed
 .Pp
 Do not forget to create the working directories so you can build ports, as
@@ -521,11 +413,6 @@ subdirectory in
 which is typically local to the client.
 You can then do builds to your heart's content!
 .Sh MAINTAINING A LOCAL BRANCH
-I have described how to maintain two versions of the source tree, a stable
-version in
-.Pa /FreeBSD/FreeBSD-4.x
-and a current version in
-.Pa /FreeBSD/FreeBSD-current .
 There is absolutely nothing preventing you
 from breaking out other versions of the source tree
 into
@@ -548,135 +435,33 @@ which can build those other operating systems.
 Many developers choose to maintain a local branch of
 .Fx
 to test patches or build a custom distribution.
-This can be done with CVS or another source code management system
-(SubVersion, Perforce, BitKeeper) with its own repository.
-Since the main
-.Fx
-tree is based on CVS, the former is convenient.
-.Pp
-First, you need to modify your
-.Xr csup 1
-environment to avoid it modifying
-the local changes you have committed to the repository.
-It is important to remove the
-.Ic delete
-keyword from your
-.Pa supfile
-and to add the
-.Pa CVSROOT
-subdirectory to your
-.Pa refuse
-file.
-For more information, see
-.Xr csup 1 .
-.Pp
-The
-.Fx
-version of
-.Xr cvs 1
-examines a custom environmental variable,
-.Ev CVS_LOCAL_BRANCH_NUM ,
-which specifies an integer to use when doing a
-.Xr cvs 1
-.Cm tag Ns / Ns Cm rtag .
-Set this number to something high (say 1000) to avoid colliding
-with potential future branches of the main repository.
-For example,
-branching a file with version 1.4 produces 1.4.1000.
-Future commits to this branch will produce revisions 1.4.1000.1,
-1.4.1000.2, etc.
+This can be done with svn or another source code management system
+(git, mercurial, Perforce, BitKeeper) with its own repository.
 .Pp
-To fork your local branch, do:
-.Bd -literal -offset 4n
-cvs rtag -r RELENG_4 -b LOCAL_RELENG_4 src
-.Ed
-.Pp
-After this, you can check out a copy from your local repository using the
-new tag and begin making changes and committing them.
-For more information on using CVS, see
-.Xr cvs 1 .
-.Pp
-.Sy WARNING!
-The
-.Xr csup 1
-utility may blow away changes made on a local branch in
-some situations.
-This has been reported to occur when the master CVS repository is
-directly manipulated or an RCS file is changed.
-At this point,
-.Xr csup 1
-notices that the client and server have entirely
-different RCS files, so it does a full replace instead of trying to
-send just deltas.
-Ideally this situation should never arise, but in the real world it
-happens all the time.
-.Pp
-While this is the only scenario where the problem should crop up,
-there have been some suspicious-sounding reports of
-.Ev CVS_LOCAL_BRANCH_NUM
-lossage that cannot be explained by this alone.
-Bottom line is, if you value your local branch then you
-should back it up before every update.
-.Sh UPDATING VIA CVS
-The advantage of using
-.Xr csup 1
-to maintain an updated copy of the CVS
-repository instead of using it to maintain source trees directly is that you
-can then pick and choose when you bring your source tree (or pieces of your
-source tree) up to date.
+.Sh "UPDATING VIA SVN"
 By using a
 .Xr cron 8
-job to maintain an updated CVS repository, you can update
-your source tree at any time without any network cost as follows:
+job to maintain an updated svn repository,
+the source tree can be
+updated at any time as follows:
 .Bd -literal -offset 4n
 (on the main development server)
-cd /usr/src
-cvs -d /home/ncvs update
-cd /usr/src2
-cvs -d /home/ncvs update
-cd /usr/ports
-cvs -d /home/ncvs update
+cd /usr
+svn update src doc ports
 .Ed
 .Pp
 It is that simple, and since you are exporting the whole lot to your
 clients, your clients have immediate visibility into the updated
 source.
 This is a good time to also remind you that most of the
-.Xr cvs 1
+.Xr svn 1
 operations you do will be done as
-.Dq Li root ,
-and that certain options are
-required for CVS to operate properly on the
-.Fx
-repository.
-For example,
-.Fl Pd
-is necessary when running
-.Nm cvs Cm update .
-These options are typically placed in your
-.Pa ~/.cvsrc
-(as already described)
-so you do not have to re-specify them every time you run a
-.Xr cvs 1
-command.
-Maintaining the CVS repository also gives you far more flexibility
-in regards to breaking out multiple versions of the source tree.
+.Dq Li root .
 It is a good idea to give your
 .Pa /FreeBSD
 partition a lot of space (I recommend
-8-12GB) precisely for that reason.
-If you can make it 15GB I would do it.
+10-15GB) precisely for that reason.
 .Pp
-I generally do not
-.Nm cvs Cm update
-via a
-.Xr cron 8
-job.
-This is because I generally want the source to not change out from under me
-when I am developing code.
-Instead I manually update the source every so often...\& when I feel it is
-a good time.
-My recommendation is to only keep the CVS repository synchronized via
 .Xr cron 8 .
 .Sh SEE ALSO
 .Xr crontab 1 ,
@@ -696,3 +481,9 @@ and first appeared
 in
 .Fx 5.0 ,
 December 2002.
+It was since extensively modified by
+.An Eitan Adler Aq eadler@FreeBSD.org
+to reflect the repository conversion from
+.Xr cvs
+to
+.Xr svn .