Rewrite portions of development.7 to make sense

in the world of subversion.

Approved by:	gjb
MFC after:	2 weeks

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
+.Xr svn 1
-to automatically pull down and maintain
+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.
+the updates will be quite small.
-.Bd -literal -offset 4n
+Run all
-mkdir /FreeBSD/FreeBSD-CVS
+.Xr svn 1
-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
 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
-mkdir /FreeBSD/FreeBSD-current
+cd /FreeBSD
-
+svn co svn://svn.freebsd.org/ports/head ports
-cd /FreeBSD/FreeBSD-4.x
+svn co svn://svn.freebsd.org/doc/head doc
-cvs -d /home/ncvs checkout -rRELENG_4 src
+svn co svn://svn.freebsd.org/base/head 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
+rm -rf src
-ln -s /FreeBSD/FreeBSD-4.x/src src	(could be -CURRENT on a client)
+ln -s /FreeBSD/src src
-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
-cd /usr
-rm -rf obj
-ln -s /FreeBSD/obj obj
-.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.
+I usually maintain my ports tree via svn or portsnap.
-It is sitting right there in the master CVS archive and I have even told you
-to check it out (see above).
 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
+Note that the ports tree exists only on the HEAD ports branch, so its always
--CURRENT even on a -STABLE box.
+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/ports ports
-ln -s /FreeBSD/FreeBSD-XXX/src src
+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
+This can be done with svn or another source code management system
-(SubVersion, Perforce, BitKeeper) with its own repository.
+(git, mercurial, 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
+.Sh "UPDATING VIA SVN"
-.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.
-.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.
 By using a
 .Xr cron 8
-job to maintain an updated CVS repository, you can update
+job to maintain an updated svn repository,
-your source tree at any time without any network cost as follows:
+the source tree can be
+updated at any time as follows:
 .Bd -literal -offset 4n
 (on the main development server)
-cd /usr/src
+cd /usr
-cvs -d /home/ncvs update
+svn update src doc ports
-cd /usr/src2
-cvs -d /home/ncvs update
-cd /usr/ports
-cvs -d /home/ncvs update
 .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 ,
+.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.
 It is a good idea to give your
 .Pa /FreeBSD
 partition a lot of space (I recommend
-8-12GB) precisely for that reason.
+10-15GB) precisely for that reason.
-If you can make it 15GB I would do it.
 .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 .