"Fossies" - the Fresh Open Source Software Archive

Member "brlcad-7.32.4/doc/notes/cvs.txt" (29 Jul 2021, 31261 Bytes) of package /linux/misc/brlcad-7.32.4.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 BRL-CAD Concurrent Versions System Policy and Guidelines
    2 ========================================================
    3 
    4 
    5 **********************************************************************
    6 NOTE: THESE INSTRUCTIONS ARE OUT-OF-DATE AS BRL-CAD NOW USES
    7 SUBVERSION INSTEAD OF CVS.  CONSULT WITH CAUTION AS SOME PORTIONS ARE
    8 STILL RELEVANT BUT OTHERS THAT ARE CVS-SPECIFIC ARE NOT.
    9 **********************************************************************
   10 
   11 
   12 The document includes a set of requirements and recommended procedures
   13 for how to effectively use CVS with this project.  Included are
   14 details on checking code in and out, effective use of commit messages,
   15 tag naming conventions, branch management, making releases, and more.
   16 Basic knowledge of CVS, its capabilities, and to a lesser extent its
   17 limitations are beyond the scope of this document.  See the CVS
   18 website and the "References" section for more information.  That said,
   19 the following general rules should always be adhered to:
   20 
   21 1. Code committed against HEAD should at least be tested and compile
   22    for the developer committing changes.  "Don't break it."
   23 
   24 2. There is a STABLE branch that may only have code committed against
   25    it that a) compiles on all relevant platforms, b) does not
   26    detrimentally degrade performance, and c) runs correctly passing
   27    available validation tests.
   28 
   29 3. Branches should be used for experimental work that would otherwise
   30    leave HEAD in an inconsistent, non-compiling, or untestable state.
   31    Branches are not merged into HEAD until the code has been tested
   32    for correct and proper functionality.
   33 
   34 4. Commit and update frequently.  Large or complicated changes should
   35    be broken up into smaller succinct commits as best possible to make
   36    reviewing easier.  Commit working code early and commit often.
   37 
   38 5. Be consistent and informative.  Tags need to follow a consistent
   39    naming convention.  Commit messages need to be informative.  Source
   40    code changes should follow existing style and be usefully
   41    commented.
   42 
   43 
   44 TABLE OF CONTENTS
   45 -----------------
   46     Introduction
   47     Table of Contents
   48     Overview
   49     Checking out sources
   50 	from HEAD
   51 	from STABLE
   52 	from a branch/revision
   53     Checking in sources
   54 	commit messages
   55 	to HEAD
   56 	to STABLE
   57 	to a branch/revision
   58     Tag naming convention
   59 	for releases
   60 	for branches
   61     Making a release
   62 	creating a maintenance branch
   63 	applying release patches
   64     Merging a branch
   65 	merging a branch into HEAD
   66 	merging HEAD into a branch
   67     Making a branch
   68     Usage Tips
   69     References
   70 
   71 
   72 OVERVIEW
   73 --------
   74 
   75     Code organizational sanity and consistency are of paramount
   76     importance.  As CVS can both help and hinder efforts to keep the
   77     sources organized, the policy and guidelines outlined herein
   78     overview the manner in which CVS should be used with this project.
   79 
   80     This CVS policy and guidelines document should be used in
   81     combination with a developer's guide that covers other aspects of
   82     code contributions and developer behavior such as how and where to
   83     provide patches, what coding styles should be used, and how to
   84     make releases.  Likewise, exact semantics of testing policy,
   85     requirements for migrating code from HEAD to STABLE, basic CVS
   86     usage, and release policy are outside the scope of this document.
   87 
   88     The intent of this document is to cover the broad aspects of how
   89     CVS is to be organized and used.  This includes branch management,
   90     tag naming conventions, checking sources in and out, and other
   91     relevant usage policy.
   92 
   93     CVS branches should be used to separate out the various types of
   94     source code revisions.  These include:
   95 
   96 	1) current or "active" sources
   97 	2) stable sources
   98 	3) releases
   99 	4) experimental sources
  100 
  101     The CVS HEAD is for active development.  A separate STABLE branch
  102     exists to hold a revision of the sources that is validated and
  103     tested across platforms.  Releases should only made off of stable
  104     revisions of the source code.  When a release is made, a
  105     maintenance branch may and should exist for making patch releases.
  106     Finally, various experimental and developer undertakings that may
  107     benefit by being isolated from changes to HEAD or STABLE, or would
  108     likewise be disruptive to normal HEAD functionality, may live on
  109     a branch of their own.
  110 
  111     It's very important that the main CVS HEAD revision be a "mostly"
  112     stable code base so that at any given time users may download the
  113     latest sources, get the source code to compile with minimal
  114     effort, and have the core components mostly function as expected.
  115     See the "Checking in sources to HEAD" section for more details.
  116 
  117     Some users and developers will need from time to time to obtain a
  118     relatively recent version of the sources that is certain or at
  119     least expected to "work".  This is what the STABLE branch is for.
  120     See the "Checking in sources to STABLE" section for more
  121     information.
  122 
  123 
  124 CHECKING OUT SOURCES
  125 --------------------
  126 
  127     There are two basic ways to check out the sources: anonymously or
  128     as a developer.  Developers have full read-write access to the
  129     source code.  Anonymous users have read-only access; and the
  130     version of the sources checked out may actually lag the most
  131     recent commits by several hours.
  132 
  133     Regardless of whether the sources are being checked out by a
  134     developer or anonymously, CVS_RSH should be set to "ssh".
  135 
  136     Anonymous users will need to login first:
  137 
  138 	cvs -d :pserver:anonymous@brlcad.brlcad.cvs.sf.net:/cvsroot/brlcad login
  139 
  140     Once logged in, the access method for anonymous users will be via
  141     :pserver: (provide an empty password if prompted).  Developers
  142     will checkout using the default implicit :ext: method and will
  143     need to provide an authorized username.  Be sure to use the "-P"
  144     checkout option to remove (prune) empty directories.  The "-z9"
  145     global CVS option is encouraged to minimize network utilization.
  146 
  147 
  148     FROM HEAD:
  149 
  150     As anonymous:
  151 	cvs -z9 -d :pserver:anonymous@brlcad.cvs.sf.net:/cvsroot/brlcad checkout -P brlcad
  152 
  153     As a developer:
  154 	cvs -z9 -d <username>@brlcad.cvs.sf.net:/cvsroot/brlcad checkout -P brlcad
  155 
  156 
  157     FROM STABLE:
  158 
  159     Checking out from STABLE is like checking out from any specific
  160     revision or branch -- provide the tag name upon checkout:
  161 
  162     As anonymous:
  163 	cvs -z9 -d :pserver:anonymous@brlcad.cvs.sf.net:/cvsroot/brlcad checkout -P -r STABLE brlcad
  164 
  165     As a developer:
  166 	cvs -z9 -d <username>@brlcad.cvs.sf.net:/cvsroot/brlcad checkout -P -r STABLE brlcad
  167 
  168 
  169     FROM A BRANCH/REVISION:
  170 
  171     The process for checking out a given revision number is pretty
  172     much a matter of knowing which revision tag name is desired, and
  173     then checking out with that symbolic tag name:
  174 
  175     As anonymous:
  176 	cvs -z9 -d :pserver:anonymous@brlcad.cvs.sf.net:/cvsroot/brlcad checkout -P -r <tagname> brlcad
  177 
  178     As a developer:
  179 	cvs -z9 -d <username>@brlcad.cvs.sf.net:/cvsroot/brlcad checkout -P -r <tagname> brlcad
  180 
  181     If the tag names are not known, you can check out HEAD or STABLE
  182     and perform a "cvs log" on any file to see the known tag names:
  183 
  184 	cd brlcad
  185 	cvs status -v README
  186 
  187     Once you find the revision or branch tag name in question, you can
  188     "cvs update" to that revision:
  189 
  190 	cvs -z9 update -r <tagname>
  191 
  192     See the CVS manual documentation for more information.
  193 
  194 
  195 CHECKING IN SOURCES
  196 -------------------
  197 
  198     Commit access is generally provided on a case-by-case basis as the
  199     need arises after careful consideration of the individual's
  200     ability to follow the project's coding style, follow this CVS
  201     commit policy, and work productively with the other developers.
  202     If you have to ask for commit access, you probably won't get it.
  203     So don't ask.  Provide patches and interact with the existing
  204     developers.
  205 
  206     If you are given commit access, you are expected to
  207     read and follow this policy and its guidelines as well as the
  208     developer's guide.
  209 
  210 
  211     COMMIT MESSAGES:
  212 
  213     When code is committed to CVS, a commit message should be provided
  214     that appropriately describes the change in a succinct and useful
  215     manner.  It's important to remember that CVS commit comments are
  216     stored per-file.  Care should be taken to not be vague,
  217     undescriptive, or ambiguous often tailoring commit messages to
  218     individual files even if the change was made as part of a larger
  219     modification.
  220 
  221     While the comments need to be descriptive and informative, they
  222     should also be as short and to the point as possible.  The CVS
  223     commit comments are not the appropriate place for legal
  224     disclaimers, usage documentation, extensive debugging details,
  225     business politics, or mini novels of who/what/when/where/why.
  226 
  227     They should be no more than a few lines long at most, normally
  228     only consisting of a short single-line statement.  CVS commit
  229     comments are for documenting changes so that other developers may
  230     derive a clue about what the change was without necessarily
  231     needing to look at the actual source differences.
  232 
  233     Instead of making generic statements about fixing or improving the
  234     source code, succinctly describe the change in a manner that may
  235     be useful for someone else reading the comment that is not
  236     familiar with the change.  If the changes are merely formatting or
  237     whitespace adjustments, a simple commit message of "ws" or "M-x
  238     indent-region" is generally understood and sufficient.
  239 
  240     If a file is being moved/renamed, the comment should include both
  241     where the file is moved from and where it was moved to in the
  242     message, e.g. "moved from librt/bool.c to src/librt/bool.c".
  243 
  244 
  245     TO HEAD:
  246 
  247     It's very important that the main CVS HEAD revision be a "mostly"
  248     stable code base so that at any given time users may download the
  249     latest source, get it to compile with minimal effort, and have the
  250     core components mostly function as expected.  HEAD is where active
  251     development takes places, so this necessarily means that there may
  252     be small windows of opportunity where the sources do not compile,
  253     but those should not persist.  Likewise, since the developers
  254     potentially and often have specific or relatively independent
  255     development efforts, the CVS commits of one developer should be
  256     made in a means that will have limited or understood impact on
  257     other developers.
  258 
  259     This minimally means that CVS commits need to at least work for
  260     the developer committing the changes.  If it's discovered that the
  261     changes break other major supported platforms, the broken state
  262     should not be allowed to linger.  Effort and arrangements need to
  263     be made to either resolve the problem promptly or the changes
  264     should be reverted.
  265 
  266 
  267     TO STABLE:
  268 
  269     Code being committed to STABLE require special attention and just
  270     a little more detail in their commit messages.
  271 
  272     Some users and developers will need from time to time to obtain a
  273     relatively recent version of the sources but a version that is
  274     certain or at least expected to "work".  This shall be known as
  275     the STABLE branch.  For code to make it to the STABLE branch, it
  276     needs to pass several criteria and commits should be well
  277     documented indicating the nature, purpose, and impact of the
  278     change.  These criteria include the following:
  279 
  280     a) Compiles -- The code must compile on all supported platforms.
  281        This generally requires coordination with other developers if
  282        access to other platforms is limited.
  283 
  284     b) Improves -- Without reasonable justification, the changes must
  285        not degrade performance, be inconsistent in style or behavior
  286        of the sources, or break support for existing functionality.
  287 
  288     c) Passes -- The changes must successfully pass any available
  289        validation tests.  If the tests are flawed or simply require
  290        modification, justification and explanation should be provided
  291        along with fixes to the tests before submitting code that would
  292        otherwise not pass validation.
  293 
  294 
  295     TO A BRANCH/REVISION:
  296 
  297     Checking in code to a branch other than STABLE generally do not
  298     necessarily need to follow the same requirements of compiling
  299     cleaning or "working" until those changes are merged back in to
  300     either STABLE or HEAD unless the branch is a release maintenance
  301     branch.  Release maintenance branches generally follow the same
  302     commit rules as checking into HEAD.
  303 
  304     As it's not possible to commit against a non-branch checkout (such
  305     as a release tag export like "rel-7-0"), changes to a revision
  306     that is otherwise immutable can still be made by performing a
  307     "diff" against a clean checkout of that same revision (unmodified)
  308     and then applying the patch to a maintenance branch or to the CVS
  309     HEAD.  See the "Applying release patches" under "Making a release"
  310     for examples.
  311 
  312 
  313 TAG NAMING CONVENTIONS
  314 ----------------------
  315     <keyword>[-<revision>][-<date>][-<comment>]
  316 
  317     <keyword> ::= { rel, ansi, jra, sean, ppc, ... }
  318 
  319 	The <keyword> is normally something short and concise.  For
  320 	release tags, it is "rel".  Other branch keywords may indicate
  321 	functionality, developers, etc.
  322 
  323     <revision> ::= <major>[-<minor>[-<patch>]]  (e.g., 6-0-2 and 5-2)
  324 
  325 	The <revision> numbering convention is fairly standard and
  326 	common practice:
  327 
  328 	<major> is the major revision number and changes relatively
  329 		infrequently.  Major releases contain significant
  330 		architectural changes and are not generally backwards
  331 		compatible with existing code or data to some extent.
  332 		They may require data and/or code to be converted in
  333 		order to upgrade.
  334 
  335 	<minor> is the minor revision number a usually changes on a
  336 		fairly regular basis.  As new features are added and
  337 		releases are made, the minor revision number changes
  338 		to reflect those additions.  Odd minor numbers
  339 		indicate a developer revision.  Even minor numbers
  340 		indicate a release revision.  Minor releases may or
  341 		may not be backwards compatible.
  342 
  343 	<patch> is the patch revision number and is used to make bug
  344 		fixes on an as-needed basis.  These changes are not
  345 		usually as extensively tested as minor and major
  346 		releases, but they should always be backwards
  347 		compatible.
  348 
  349     <date> := YYYYMMDD (e.g., 20021231)
  350 
  351 	When creating tags, the date a tag is made is sometimes noted
  352 	and useful or even recommended.  The format of the date is
  353 	YYYYMMDD and should correspond to tag creation dates.  Branch
  354 	and release tags should not include a date in the tag name.
  355 
  356     <comment>
  357 
  358 	For branches the comment is "branch".  For releases, it is
  359 	left blank.  For other miscellaneous tags, the comment is up
  360 	to the person tagging.
  361 
  362     Note that hyphens (-) are used, not underscores.  Periods (.) are
  363     never used because they upset CVS's branch naming.
  364 
  365     Tag names (including branches) should be in lower case only.
  366     Upper case is reserved for HEAD and STABLE.
  367 
  368     Non-branch tags are used for 1) marking a release, 2) merging
  369     branches, and 3) miscellaneous tags (e.g., to remember a specific
  370     starting or stopping point).
  371 
  372 
  373     FOR RELEASES:
  374 
  375 	Release tags are used to indicate a revision of the source
  376 	code that was made publicly available.  It should match the
  377 	sources released, bugs and all, so that proper and useful
  378 	diffs may be made.  The format for release tags is:
  379 
  380 	rel-<revision>
  381 
  382 	    <revision> ::= <major>-<minor>[-<patch>]
  383 
  384 	    The revision number should match the version reported by
  385 	    the source code.
  386 
  387 	Examples: rel-6-0 rel-7-2-5
  388 
  389 
  390     FOR BRANCHES:
  391 
  392 	Branches are symbolic tags that are used to denote and allow
  393 	separate isolated revisions of code.  The following format
  394 	should be used for branch tags:
  395 
  396 	<keyword>[-<revision>]-branch
  397 
  398 	    <keyword> ::= describes the purpose of the branch.
  399 
  400 	    If the branch is a maintenance branch, the keyword should
  401 	    match the revision's keyword and revision.
  402 
  403 	Examples: rel-7-0-branch ansi-branch photonmap-branch
  404 
  405 
  406     FORMAT FOR MERGES:
  407 
  408 	When joining a branch that has a large set of changes into
  409 	HEAD, there should be a tag before and after the merge.  When
  410 	joining HEAD into a branch, tagging is optional. Joins into
  411 	head should be tagged, though.
  412 
  413 	On HEAD before the merge, use the following tag format:
  414 
  415 	    premerge[-<revision>][-<date>]-<comment>
  416 
  417 	    Example: premerge-20040404-ansi
  418 
  419 	On HEAD after the merge, use the following tag format:
  420 
  421 	    postmerge[-<revision>][-<date>]-<comment>
  422 
  423 	    Example: postmerge-20040315-windows
  424 
  425 	The <comment> should be a simple identifying keyword.  The
  426 	branch keyword being merged suffices quite well.  A date is
  427 	preferred.
  428 
  429 	If development on a particular branch is considered "final",
  430 	it should be marked with a "freeze" tag on the branch:
  431 
  432 	    <keyword>[-<revision>][-<date>]-freeze
  433 
  434 	    Example: windows-20040315-freeze
  435 
  436 	If applying patches directly to the CVS HEAD where there is
  437 	potential to need to revert the changes, using "pre" and
  438 	"post" as the tag comment is appropriate.
  439 
  440 	    <keyword>[-<revision>][-<date>]-pre
  441 	    <keyword>[-<revision>][-<date>]-post
  442 
  443 	    Examples: hartley-6-0-pre ctj-4-5-post offsite-5-3-pre
  444 
  445 
  446     FORMAT FOR MISCELLANEOUS TAGS:
  447 
  448 	For everything else, the basic structure of the tags still
  449 	applies.  Lower case, dash-separated, and hopefully succinctly
  450 	informative tag names should be used.  Dates are highly
  451 	recommended as CVS tags are not associated by date, but rather
  452 	to the individual revision of a file.
  453 
  454 	<keyword>[-<revision>][-<date>][-<comment>]
  455 
  456     When in doubt, tag.  It's easy to remove or rename tags, but it
  457     can be rather complicated to create one after the fact.
  458 
  459 
  460 MAKING A RELEASE
  461 ----------------
  462 
  463     Making a release is generally a matter of making sure that all
  464     desired code changes are committed and well tested.  Code
  465     committed to HEAD should be well tested by performing any
  466     validation steps required to migrate those changes to STABLE.
  467     Once HEAD is verified, it may be joined into STABLE, which should
  468     likewise be thoroughly tested.
  469 
  470     Once all the code is verified, the release should be tagged:
  471 
  472 	cvs tag rel-<revision>
  473 
  474     Revision numbers should follow a numbering convention consistent
  475     with the developer guidelines.  Minor and patch revision numbers
  476     that are odd numbered are used to denote developer revisions of
  477     the source code.  Release tags should use even numbers for the
  478     minor and patch revision numbers.  See the "Tag naming convention"
  479     section for more details.
  480 
  481 
  482     CREATING A MAINTENANCE BRANCH:
  483 
  484     If minor maintenance is expected to continue or development on
  485     HEAD needs to continue in an incompatible manner, a maintenance
  486     branch should be made:
  487 
  488 	cvs rtag -r rel-<revision> -b rel-<revision>-branch
  489 
  490     That will create a branch named rel-<revision>-branch anchored at
  491     the same revision of the sources as rel-<revision>.
  492 
  493 
  494     APPLYING RELEASE PATCHES:
  495 
  496     In general, unified diff patches should be requested from people
  497     providing patches whenever possible.  For people working with a
  498     cvs checkout, generating a diff is generally a simple matter of
  499     running:
  500 
  501 	cvs diff -u > my.patch
  502 
  503     This will create a unified diff patch file called "my.patch" that
  504     is trivially applied to a checkout using the patch command:
  505 
  506 	patch -p0 < my.patch
  507 
  508     Assuming there have not been overlapping/conflicting changes,
  509     patch should say on the first attempt that all chunks were
  510     successfully applied.  If not, there will be reject files that
  511     will have changes that need to be manually reviewed and resolved..
  512 
  513     Users who are perhaps working off of a source tarball instead of a
  514     CVS checkout can fairly easily generate a unified diff patch by
  515     comparing their modified tree against an unmodified source tree:
  516 
  517 	diff -u brlcad brlcad.modified > my.patch
  518 
  519     In this example, brlcad is an unmodified top-level source
  520     directory and "brlcad.modified" is a top-level source directory
  521     that has been modified.  That same patch file may then be applied
  522     to a checkout and committed to CVS.
  523 
  524     If there is an active maintenance branch that a patch was started
  525     from, it is generally easier to apply the patch to the maintenance
  526     branch first and then join the maintenance branch into HEAD per
  527     the usual means to join branch changes into HEAD instead of
  528     merging directly into the CVS HEAD.  HEAD will have often changed
  529     too significantly and may result in patch being unable to resolve
  530     chunks.  See the patch manual documentation for more details.
  531 
  532     Failing any of the above, patches may also be applied manually.
  533     This is often even desirable to become more familiar with the
  534     changes being made providing an opportunity for a healthy peer
  535     review.
  536 
  537 
  538 MERGING A BRANCH
  539 ----------------
  540     CVS branches can be both very useful or difficult.  Proper usage
  541     of branches generally requires a firm understanding of CVS
  542     otherwise complications and mistakes are bound to happen as there
  543     are several usage pitfalls.  Following the directions shown below
  544     should help avoid the pitfalls and assist in making effective use
  545     of a CVS branch.
  546 
  547     Regardless if the branch is a maintenance branch or the STABLE
  548     branch, the fundamental "action" in performing a merge is called a
  549     CVS join.  You can join code committed to one branch revision into
  550     another branch revision by passing the "-j" option to the cvs
  551     update command.  It's important to note that joins occur from code
  552     that is already committed.
  553 
  554     Once the code is joined, it may be committed to CVS.  If you have
  555     changes on a branch that have not yet been committed, they should
  556     first be committed before attempting the join.
  557 
  558 
  559     MERGING A BRANCH INTO HEAD:
  560 
  561     Merging branches in CVS is generally a matter of "joining" in the
  562     changes from one the branch revision into another branch revision.
  563     HEAD can itself be considered a branch.  If, for example, you have
  564     a maintenance branch named "rel-7-0-branch" that has had changes
  565     applied to it and you wish to apply those same changes to HEAD you
  566     would checkout HEAD:
  567 
  568 	  cvs -z9 -d <CVSROOT> checkout -kk -P brlcad
  569 
  570     The join the changes from the desired branch:
  571 
  572 	  cvs update -kk -dP
  573 	  cvs tag premerge-<revision>-<date>-<comment>
  574 	  cvs update -kk -dP -j rel-7-0-branch
  575 	  [ resolve conflicts & test ]
  576 	  cvs commit
  577 	  cvs tag postmerge-<revision>-<date>-<comment>
  578 
  579     The comment should contain or be the keyword of the branch being
  580     merged in.  For example, "premerge-20040315-windows" indicates a
  581     merge that occurred on March 15th, 2004, from the windows-branch.
  582 
  583     If there are any conflicts, they would of course need to be
  584     manually resolved.  Once any conflicts are resolved and the
  585     sources are tested for functionality, the changes could then be
  586     committed to HEAD.  Be careful to notice any file additions or
  587     deletions as CVS, generally speaking, will not manage those for
  588     you until they are committed.
  589 
  590     In both the checkout and the join update, the -kk flag was used to
  591     cause CVS to not expand the CVS variables such as \$Revision\$ and
  592     \$Id\$.  If those keyword variables are expanded, you're likely to
  593     have many conflicts depending on time-stamps.
  594 
  595     If the branch being checked in an extensive set of changes,
  596     testing is essential.  It is also a good idea to warn other
  597     developers of what you are planning to do.  You should indicate
  598     what parts of the system will be affected and coordinate in detail
  599     with other developers as appropriate.
  600 
  601 
  602     MERGING HEAD INTO A BRANCH:
  603 
  604     Merging changes from HEAD into a branch (such as STABLE) is not
  605     really any different than the scenario described for merging a
  606     branch into HEAD.  Again, HEAD itself can be simply considered a
  607     branch too.  For example with an existing branch checkout:
  608 
  609 	cvs update -kk
  610 	cvs update -kk -j HEAD
  611 	[resolve conflicts & test ]
  612 	cvs commit
  613 
  614     The important step to realize is that your working checkout needs
  615     to be the revision you want to join changes into.  When in doubt,
  616     commit all your changes to the appropriate branch, delete all your
  617     sources, and checkout fresh.  "cvs status README" will tell you
  618     what revision you have checked out.  It will be listed as a
  619     "Sticky Tag".
  620 
  621 
  622 MAKING A BRANCH
  623 ---------------
  624     Making a branch is a matter of using the "-b" option when tagging.
  625     Branch tags are special symbolic CVS tags that allow for isolated
  626     changes and controlled merging of modifications.
  627 
  628     CASE 1: You have no checked out source code revision:
  629 
  630 	If you want to use the latest sources on the CVS HEAD as the
  631 	starting point for your branch:
  632 
  633 	    cvs rtag -b <keyword>-branch brlcad
  634 	    cvs checkout -r <keyword>-branch brlcad
  635 
  636 	If you want to use some other tag as the starting point for
  637 	your branch:
  638 
  639 	    cvs rtag -b -r <tag> <keyword>-branch brlcad
  640 	    cvs checkout -r <keyword>-branch brlcad
  641 
  642     CASE 2: You have a checked out revision with all changes committed
  643     and you want to tag it and start using it as a branch:
  644 
  645 	cvs tag -b <keyword>-branch
  646 	cvs update -dP -r <keyword>-branch
  647 
  648     CVS will denote the tag as a "sticky" tag to indicate which
  649     version is currently checked out.  You can verify this by using
  650     'cvs status', for example:
  651 
  652 	cvs status README
  653 
  654     To see all tags that have been set for a particular file in
  655     addition to checkout status, use the "-v" status option:
  656 
  657 	cvs status -v README
  658 
  659     or via the generally more detailed file log:
  660 
  661 	cvs log README
  662 
  663 
  664 USAGE TIPS
  665 ----------
  666     0) Checkout with the -P option to prune empty directories:
  667 
  668        cvs checkout -P brlcad
  669 
  670     1) Be sure to perform an "update -dP" to check for new directories
  671        from time to time and to prune empty ones.
  672 
  673        cvs update -dP
  674 
  675     2) Update and commit frequently.  Frequent updates are a good
  676        thing.  Perform them often to minimize conflicts.
  677 
  678     4) A convenient way to check what files have been modified when
  679        you are certain that you've not added files:
  680 
  681        cvs -q update | grep -v \?
  682 
  683        That performs a quiet update (the directory tree isn't output)
  684        and ignores lines that have a question mark (normally build
  685        files).
  686 
  687     3) To avoid having to specify the repository for a checkout, you
  688        can set your CVSROOT environment variable to the location of
  689        the repository:
  690 
  691        For anonymous users:
  692 	   export CVSROOT=:pserver:anonymous@brlcad.cvs.sf.net:/cvsroot/brlcad
  693 
  694        For developers with accounts:
  695 	   export CVSROOT=<username>@brlcad.cvs.sf.net:/cvsroot/brlcad
  696 
  697     5) CVS does not manage directories so care must be taken when
  698        creating new directories or moving things around.  Do NOT add
  699        directories that include non-static information as part of the
  700        directory name.  Examples include adding directories that
  701        include a version in their name (e.g. libtcl8), indicate age
  702        (e.g. newRt), or contain other volatile data.
  703 
  704     6) If you need to move a directory, rethink why and try not to.
  705        If you still need to move a directory, .. try to find another
  706        way to cope.  If you still REALLY need to move a directory, a
  707        little find scripting can make it easy.  In case you didn't get
  708        the hint DO NOT MOVE/RENAME DIRECTORIES unless there's a _very_
  709        good reason.  This implicitly means that extra care and thought
  710        should be made when naming new directories to be added to the
  711        repository.
  712 
  713     7) It is possible to move directories using a little find
  714        scripting.  Assuming you've not got build files cluttering
  715        things up and are ready to simply move files to a new location
  716        in CVS, an otherwise complicated task becomes mostly simple
  717        with a few find scripts.  Here is an example where a directory
  718        ./foo/ is moved to a new location ./src/foo2/:
  719 
  720        cd foo
  721        # copy the files to their new home
  722        find . -type d -not -name CVS -exec mkdir -p ../src/foo2/{} \;
  723        find . -type f -not -regex '.*/CVS/.*' -exec cp -p {} ../src/foo2/{} \;
  724        cd ../src
  725        # add the new directories to cvs
  726        find foo2 -type d -not -name CVS -exec cvs add {} \;
  727        find foo2 -type f -not -regex '.*/CVS/.*' -exec cvs add {} \;
  728        # commit the new sources
  729        cvs commit -m "moved from foo to src/foo" foo2
  730        cd ..
  731        # delete the old source subtree
  732        find foo -type f -not -regex '.*/CVS/.*' -exec rm {} \;
  733        find foo -type d -not -name CVS -exec rm -f {} \; -exec cvs delete {} \;
  734        cvs commit -m "moved from foo to src/foo" foo
  735        cvs update -P foo
  736 
  737        If you don't have CVS keys set up and have too many files to
  738        move, each find script could be passed to xargs so that only a
  739        single password is prompted instead of one per file.  Since
  740        moving/renamed directories in CVS is "bad", though, that's left
  741        as an exercise to the reader.
  742 
  743     8) When renaming files, be sure to indicate both where the file
  744        was moved from and where it was moved to and/or the name before
  745        the move and the name after the move.  Do this both on
  746        committing the file deletion and on committing the file
  747        addition.  This way, people reading the file's log will know
  748        where to find the rest of the file's history.
  749 
  750     9) If experiencing trouble consolidating conflicts that involve
  751        CVS "$" variables, set the keyword sticky flag which will tell
  752        CVS to not perform the keyword variable expansions.  Perform a
  753        "cvs update -kk" and the conflicts should go away.
  754 
  755    10) Denote binary files as binary in CVS via the
  756        CVSROOT/cvswrappers administrative file or via the "-kb" option
  757        when adding files.  In the CVSROOT/cvswrappers file, the
  758        following line would denote files ending in ".pix" as binary:
  759 
  760        *.pix -k 'b'
  761 
  762        You can likewise denote arbitrary files as binary via the "-kb"
  763        option on commit:
  764 
  765        cvs add -kb new_file_name_here
  766 
  767        If the file has already been added to CVS, it may be
  768        administratively marked as a binary file after the fact using
  769        the "cvs admin" command:
  770 
  771        cvs admin -kb some_existing_file
  772        cvs update -A some_existing_file
  773 
  774 
  775 REFERENCES
  776 ----------
  777     This CVS policy and guidelines document was in part derived off
  778     some of the principal ideas of other projects' usage of CVS such
  779     as the Linux Documentation Project, the XFree86 DRI project, Zope,
  780     FreeBSD, and AT&T's SML/NJ among others.
  781 
  782 Version Management with CVS
  783 https://www.cvshome.org/docs/manual/
  784 
  785 CVS Best Practices
  786 http://www.magic-cauldron.com/cm/cvs-bestpractices/index.html
  787 
  788 XFree86 Direct Rendering Infrastructure CvsPolicy
  789 http://dri.sourceforge.net/cgi-bin/moin.cgi/CvsPolicy
  790 http://dri.sourceforge.net/doc/cvspolicy.txt
  791 
  792 Zope
  793 http://dev.zope.org/CVS/ZopeReleasePolicy
  794 
  795 FreeBSD
  796 http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/cvs-tags.html
  797 
  798 AT&T SML/NJ
  799 http://www.smlnj.org/DEV/policy.html
  800 http://cm.bell-labs.com/cm/cs/what/smlnj/DEV/policy.html
  801 
  802 ---
  803 This document was initially written in 2002 and later almost
  804 completely rewritten in 2004 by Christopher Sean Morrison.