2689 lines
65 KiB
HTML
2689 lines
65 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
<HTML
|
||
><HEAD
|
||
><TITLE
|
||
>CVS Best Practices</TITLE
|
||
><META
|
||
NAME="GENERATOR"
|
||
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
|
||
><BODY
|
||
CLASS="article"
|
||
BGCOLOR="#FFFFFF"
|
||
TEXT="#000000"
|
||
LINK="#0000FF"
|
||
VLINK="#840084"
|
||
ALINK="#0000FF"
|
||
><DIV
|
||
CLASS="ARTICLE"
|
||
><DIV
|
||
CLASS="TITLEPAGE"
|
||
><H1
|
||
CLASS="title"
|
||
><A
|
||
NAME="AEN1"
|
||
></A
|
||
>CVS Best Practices</H1
|
||
><H3
|
||
CLASS="author"
|
||
><A
|
||
NAME="AEN4"
|
||
>Vivek Venugopalan</A
|
||
></H3
|
||
><DIV
|
||
CLASS="affiliation"
|
||
><DIV
|
||
CLASS="address"
|
||
><P
|
||
CLASS="address"
|
||
><TT
|
||
CLASS="email"
|
||
><<A
|
||
HREF="mailto:vivekv at yahoo dot com"
|
||
>vivekv at yahoo dot com</A
|
||
>></TT
|
||
></P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="revhistory"
|
||
><TABLE
|
||
WIDTH="100%"
|
||
BORDER="0"
|
||
><TR
|
||
><TH
|
||
ALIGN="LEFT"
|
||
VALIGN="TOP"
|
||
COLSPAN="3"
|
||
><B
|
||
>Revision History</B
|
||
></TH
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revision 0.7</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>2005-10-15</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revised by: vv</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
COLSPAN="3"
|
||
>A bunch of minor fixes as suggested by readers.</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revision 0.6</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>2002-09-10</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revised by: vv</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
COLSPAN="3"
|
||
>Added content related to tagging and daily builds. Changed
|
||
Linuxdoc URLs to tldp. Fixed stale links and added other corrections
|
||
suggested by readers.</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revision 0.5</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>2002-08-25</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revised by: vv</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
COLSPAN="3"
|
||
>Fixed some more errors in the document and added references to
|
||
other CVS sources and some server side scripting</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revision 0.4</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>2002-03-10</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revised by: vv</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
COLSPAN="3"
|
||
>Added new email address, Added an example flow to show how the
|
||
practices help</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revision 0.3</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>2001-12-06</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revised by: vv</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
COLSPAN="3"
|
||
>Grammatical errors cleanup</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revision 0.2</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>2001-11-27</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revised by: vv</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
COLSPAN="3"
|
||
>Incorporated first round of feedback and
|
||
some minor fixes</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revision 0.1</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>2001-11-20</TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
>Revised by: vv</TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
ALIGN="LEFT"
|
||
COLSPAN="3"
|
||
>Created</TD
|
||
></TR
|
||
></TABLE
|
||
></DIV
|
||
><HR></DIV
|
||
><DIV
|
||
CLASS="TOC"
|
||
><DL
|
||
><DT
|
||
><B
|
||
>Table of Contents</B
|
||
></DT
|
||
><DT
|
||
>1. <A
|
||
HREF="#section1-intro"
|
||
>Introduction</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>1.1. <A
|
||
HREF="#copyright"
|
||
>Copyright Information</A
|
||
></DT
|
||
><DT
|
||
>1.2. <A
|
||
HREF="#disclaimer"
|
||
>Disclaimer</A
|
||
></DT
|
||
><DT
|
||
>1.3. <A
|
||
HREF="#newversions"
|
||
>New Versions</A
|
||
></DT
|
||
><DT
|
||
>1.4. <A
|
||
HREF="#credits"
|
||
>Credits</A
|
||
></DT
|
||
><DT
|
||
>1.5. <A
|
||
HREF="#feedback"
|
||
>Feedback</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>2. <A
|
||
HREF="#section1-focusareas"
|
||
>Focus Areas</A
|
||
></DT
|
||
><DT
|
||
>3. <A
|
||
HREF="#section1-guitools"
|
||
>Using <SPAN
|
||
CLASS="acronym"
|
||
>GUI</SPAN
|
||
> Tools</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>3.1. <A
|
||
HREF="#section2-useguiclient"
|
||
>Use GUI CVS client</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>4. <A
|
||
HREF="#section1-devsandbox"
|
||
>Developer Sandbox</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>4.1. <A
|
||
HREF="#section2-clockinsync"
|
||
>Keep System clocks in Sync</A
|
||
></DT
|
||
><DT
|
||
>4.2. <A
|
||
HREF="#section2-dontshare"
|
||
>Do not share the sandbox</A
|
||
></DT
|
||
><DT
|
||
>4.3. <A
|
||
HREF="#section2-syncup"
|
||
>Stay in sync with the repository</A
|
||
></DT
|
||
><DT
|
||
>4.4. <A
|
||
HREF="#section2-workinside"
|
||
>Do not work outside the sandbox</A
|
||
></DT
|
||
><DT
|
||
>4.5. <A
|
||
HREF="#section2-cleanupatcompletion"
|
||
>Cleanup after Completion</A
|
||
></DT
|
||
><DT
|
||
>4.6. <A
|
||
HREF="#section2-checkin"
|
||
>Check-in Often</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>5. <A
|
||
HREF="#section1-serverconfig"
|
||
>CVS Server Configuration</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>5.1. <A
|
||
HREF="#section2-accesscontrol"
|
||
>CVS access control</A
|
||
></DT
|
||
><DT
|
||
>5.2. <A
|
||
HREF="#section2-scripting"
|
||
>Server side scripting</A
|
||
></DT
|
||
><DT
|
||
>5.3. <A
|
||
HREF="#section2-notification"
|
||
>Server Notification</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>6. <A
|
||
HREF="#section1-branchmerge"
|
||
>Branching and Merging</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>6.1. <A
|
||
HREF="#section2-branchowner"
|
||
>Assign ownership to Trunk and Branches</A
|
||
></DT
|
||
><DT
|
||
>6.2. <A
|
||
HREF="#section2-tagrelease"
|
||
>Tag each release</A
|
||
></DT
|
||
><DT
|
||
>6.3. <A
|
||
HREF="#section2-branchatrelease"
|
||
>Create a branch after each release</A
|
||
></DT
|
||
><DT
|
||
>6.4. <A
|
||
HREF="#section2-bugfixbranches"
|
||
>Make bug fixes to branches only</A
|
||
></DT
|
||
><DT
|
||
>6.5. <A
|
||
HREF="#section2-patchesfrombranches"
|
||
>Make patch releases from branches only</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>7. <A
|
||
HREF="#section1-chgpropagation"
|
||
>Change Propagation</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>7.1. <A
|
||
HREF="#section2-mergebugfix"
|
||
>Merge branch with the trunk after release</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>8. <A
|
||
HREF="#section1-softwarebuild"
|
||
>Software Builds</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>8.1. <A
|
||
HREF="#section2-bebo"
|
||
>Build Early and Build Often (<SPAN
|
||
CLASS="acronym"
|
||
>BEBO</SPAN
|
||
>)</A
|
||
></DT
|
||
><DT
|
||
>8.2. <A
|
||
HREF="#section2-automate"
|
||
>Automate build Process completely</A
|
||
></DT
|
||
><DT
|
||
>8.3. <A
|
||
HREF="#section2-ensurecheckin"
|
||
>All necessary files must be checked-in before build</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>9. <A
|
||
HREF="#section1-instprocess"
|
||
>Institutionalize CVS in the Organization</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>9.1. <A
|
||
HREF="#section2-chngmgmt"
|
||
>Implement Change Management Process</A
|
||
></DT
|
||
><DT
|
||
>9.2. <A
|
||
HREF="#section2-objectives"
|
||
>Make CVS Usage part of Objectives</A
|
||
></DT
|
||
><DT
|
||
>9.3. <A
|
||
HREF="#section2-metrics"
|
||
>Collect metrics on CVS usage</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>10. <A
|
||
HREF="#section1-inaction"
|
||
>Best Practices in Action</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>10.1. <A
|
||
HREF="#section2-inception"
|
||
>Inception</A
|
||
></DT
|
||
><DT
|
||
>10.2. <A
|
||
HREF="#section2-dand"
|
||
>Development and Delivery</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
><DT
|
||
>11. <A
|
||
HREF="#section1-conclusion"
|
||
>Conclusion</A
|
||
></DT
|
||
><DT
|
||
>A. <A
|
||
HREF="#gfdl"
|
||
>GNU Free Documentation License</A
|
||
></DT
|
||
><DD
|
||
><DL
|
||
><DT
|
||
>0. <A
|
||
HREF="#AEN435"
|
||
>Preamble</A
|
||
></DT
|
||
><DT
|
||
>1. <A
|
||
HREF="#AEN440"
|
||
>Applicability and Definitions</A
|
||
></DT
|
||
><DT
|
||
>2. <A
|
||
HREF="#AEN450"
|
||
>Verbatim Copying</A
|
||
></DT
|
||
><DT
|
||
>3. <A
|
||
HREF="#AEN454"
|
||
>Copying in Quantity</A
|
||
></DT
|
||
><DT
|
||
>4. <A
|
||
HREF="#AEN460"
|
||
>Modifications</A
|
||
></DT
|
||
><DT
|
||
>5. <A
|
||
HREF="#AEN496"
|
||
>Combining Documents</A
|
||
></DT
|
||
><DT
|
||
>6. <A
|
||
HREF="#AEN501"
|
||
>Collections of Documents</A
|
||
></DT
|
||
><DT
|
||
>7. <A
|
||
HREF="#AEN505"
|
||
>Aggregation with Independent Works</A
|
||
></DT
|
||
><DT
|
||
>8. <A
|
||
HREF="#AEN509"
|
||
>Translation</A
|
||
></DT
|
||
><DT
|
||
>9. <A
|
||
HREF="#AEN512"
|
||
>Termination</A
|
||
></DT
|
||
><DT
|
||
>10. <A
|
||
HREF="#AEN515"
|
||
>Future Revisions of this License</A
|
||
></DT
|
||
><DT
|
||
><A
|
||
HREF="#AEN520"
|
||
>How to use this License for your documents</A
|
||
></DT
|
||
></DL
|
||
></DD
|
||
></DL
|
||
></DIV
|
||
><BLOCKQUOTE
|
||
CLASS="ABSTRACT"
|
||
><DIV
|
||
CLASS="abstract"
|
||
><A
|
||
NAME="AEN46"
|
||
></A
|
||
><P
|
||
></P
|
||
><P
|
||
>This article explores some of the best practices that can be adopted
|
||
while using CVS as the configuration management tool in your software
|
||
projects.
|
||
</P
|
||
><P
|
||
></P
|
||
></DIV
|
||
></BLOCKQUOTE
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-intro"
|
||
></A
|
||
>1. Introduction</H1
|
||
><A
|
||
NAME="AEN52"
|
||
></A
|
||
><TABLE
|
||
BORDER="0"
|
||
WIDTH="100%"
|
||
CELLSPACING="0"
|
||
CELLPADDING="0"
|
||
CLASS="BLOCKQUOTE"
|
||
><TR
|
||
><TD
|
||
WIDTH="10%"
|
||
VALIGN="TOP"
|
||
> </TD
|
||
><TD
|
||
WIDTH="80%"
|
||
VALIGN="TOP"
|
||
><P
|
||
CLASS="literallayout"
|
||
>Men have become the tools of their tools. <br>
|
||
</P
|
||
></TD
|
||
><TD
|
||
WIDTH="10%"
|
||
VALIGN="TOP"
|
||
> </TD
|
||
></TR
|
||
><TR
|
||
><TD
|
||
COLSPAN="2"
|
||
ALIGN="RIGHT"
|
||
VALIGN="TOP"
|
||
>--<SPAN
|
||
CLASS="attribution"
|
||
>Henry David Thoreau (1817-1862)
|
||
</SPAN
|
||
></TD
|
||
><TD
|
||
WIDTH="10%"
|
||
> </TD
|
||
></TR
|
||
></TABLE
|
||
><P
|
||
>This article outlines some of the best practices that can be adopted
|
||
when Concurrent Versions System is used as the configuration management tool in your software
|
||
project. </P
|
||
><P
|
||
>Concurrent Versions System (CVS) is an <A
|
||
HREF="http://www.opensource.org"
|
||
TARGET="_top"
|
||
>Open Source</A
|
||
> configuration management
|
||
tool that is now being looked at seriously by many commercial organizations as
|
||
a viable alternative to other commercial Software configuration management tools. </P
|
||
><P
|
||
>This spotlight on CVS has led to the inevitable question of best
|
||
practices for deploying CVS as the backbone SCM tool for large
|
||
software development projects. Having answered this question many times
|
||
verbally as a bunch of <SPAN
|
||
CLASS="QUOTE"
|
||
>"gotchas"</SPAN
|
||
> on CVS, it was time to put
|
||
down on paper some of the best practices that will work well for
|
||
CVS based projects. </P
|
||
><DIV
|
||
CLASS="note"
|
||
><P
|
||
></P
|
||
><TABLE
|
||
CLASS="note"
|
||
WIDTH="100%"
|
||
BORDER="0"
|
||
><TR
|
||
><TD
|
||
WIDTH="25"
|
||
ALIGN="CENTER"
|
||
VALIGN="TOP"
|
||
><IMG
|
||
SRC="../images/note.gif"
|
||
HSPACE="5"
|
||
ALT="Note"></TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
VALIGN="TOP"
|
||
><P
|
||
>This paper assumes that the reader is familiar with the
|
||
fundamentals of software version control. Including features like
|
||
branching, merging, tagging (labelling) etc., offered by modern version
|
||
control tools such as CVS </P
|
||
><P
|
||
>Further, This paper is not an introduction to CVS and its usage. There are
|
||
excellent articles available on the net for the same. This paper assumes
|
||
that the reader is familiar with CVS commands and is looking at
|
||
deploying CVS in his or her organization. Some of the popular
|
||
CVS related links that can provide CVS education are. </P
|
||
><P
|
||
></P
|
||
><OL
|
||
TYPE="1"
|
||
><LI
|
||
><P
|
||
>The <A
|
||
HREF="http://ximbiot.com/cvs/wiki/index.php?title=Main_Page"
|
||
TARGET="_top"
|
||
>Concurrent Versions System site</A
|
||
> where
|
||
current informaton about CVS is available. Including the <A
|
||
HREF="http://ximbiot.com/cvs/wiki/index.php?title=Cederqvist"
|
||
TARGET="_top"
|
||
>CVS manual</A
|
||
>.
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Karl Fogel's book, <A
|
||
HREF="http://cvsbook.red-bean.com"
|
||
TARGET="_top"
|
||
>Open Source Development with
|
||
CVS</A
|
||
> is available online.
|
||
</P
|
||
></LI
|
||
></OL
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="copyright"
|
||
></A
|
||
>1.1. Copyright Information</H2
|
||
><P
|
||
> This document is Copyright <20> 2001 Vivek Venugopalan. Permission
|
||
is granted to copy, distribute and/or modify this document under the terms of
|
||
the <A
|
||
HREF="#gfdl"
|
||
><I
|
||
CLASS="citetitle"
|
||
>GNU Free Documentation
|
||
License</I
|
||
></A
|
||
>, Version 1.1 or any later version published by the
|
||
Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and
|
||
no Back-Cover Texts. A copy of the license can be found in <A
|
||
HREF="#gfdl"
|
||
>Appendix A</A
|
||
>. </P
|
||
><P
|
||
> This document may be reproduced and distributed in whole or in part, in
|
||
any medium physical or electronic, as long as this copyright notice is
|
||
retained on all copies. Commercial redistribution is allowed and encouraged;
|
||
however, the author would like to be notified of any such distributions.
|
||
</P
|
||
><P
|
||
> All translations, derivative works, or aggregate works incorporating
|
||
this document must be covered under this copyright notice. That is, you may
|
||
not produce a derivative work from this document and impose additional
|
||
restrictions on its distribution. Exceptions to these rules may be granted
|
||
under certain conditions; please contact the author at the address given
|
||
below. </P
|
||
><P
|
||
> In short, we wish to promote dissemination of this information through
|
||
as many channels as possible. However, we do wish to retain copyright on the
|
||
document, and would like to be notified of any plans to redistribute the same.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="disclaimer"
|
||
></A
|
||
>1.2. Disclaimer</H2
|
||
><P
|
||
> No liability for the contents of this document can be accepted. Use
|
||
the concepts, examples and other content at your own risk. As this is a new
|
||
edition of this document, there may be errors and inaccuracies that may of
|
||
course be damaging to your system. Proceed with caution, and although this is
|
||
highly unlikely, the author(s) do not take any responsibility whatsoever.
|
||
</P
|
||
><P
|
||
> All copyrights are held by their respective owners, unless specifically
|
||
noted otherwise. Use of a term in this document should not be regarded as
|
||
affecting the validity of any trademark or service mark. </P
|
||
><P
|
||
> Naming of particular products or brands should not be seen as
|
||
endorsements. </P
|
||
><P
|
||
> You are strongly recommended to take a backup of your system before
|
||
major installation and backups at regular intervals. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="newversions"
|
||
></A
|
||
>1.3. New Versions</H2
|
||
><P
|
||
> This document is Version : 0.7. </P
|
||
><P
|
||
> The latest version of this document can be obtained from (In the order of latest version availability) </P
|
||
><P
|
||
></P
|
||
><OL
|
||
TYPE="1"
|
||
><LI
|
||
><P
|
||
> <A
|
||
HREF="http://www.sanchivi.com/cm/cvs-bestpractices/index.html"
|
||
TARGET="_top"
|
||
>My website</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
> <A
|
||
HREF="http://tldp.org/REF/CVS-BestPractices/html/index.html"
|
||
TARGET="_top"
|
||
>The linux documentation project</A
|
||
>
|
||
</P
|
||
></LI
|
||
></OL
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="credits"
|
||
></A
|
||
>1.4. Credits</H2
|
||
><P
|
||
>The list of people who have provided information and correction for this
|
||
paper in no particular order are.
|
||
<P
|
||
></P
|
||
><OL
|
||
TYPE="1"
|
||
><LI
|
||
><P
|
||
>Jens-Uwe Mager </P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Jorgen Grahn </P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Thomas S. Urban </P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Cam Mayor </P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Sally Miller</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Niels Jakob Darger</P
|
||
></LI
|
||
></OL
|
||
>
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="feedback"
|
||
></A
|
||
>1.5. Feedback</H2
|
||
><P
|
||
> Feedback is most certainly welcome for this document. Without your
|
||
submissions and input, this document wouldn't exist. Please send your
|
||
additions, comments and criticisms to the following email address :
|
||
<TT
|
||
CLASS="email"
|
||
><<A
|
||
HREF="mailto:vivekv at yahoo dot com"
|
||
>vivekv at yahoo dot com</A
|
||
>></TT
|
||
>. </P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-focusareas"
|
||
></A
|
||
>2. Focus Areas</H1
|
||
><P
|
||
>The focus areas for best practice are
|
||
</P
|
||
><P
|
||
></P
|
||
><OL
|
||
TYPE="1"
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section1-guitools"
|
||
>GUI Tools</A
|
||
>
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-useguiclient"
|
||
>Use GUI CVS client</A
|
||
>
|
||
</P
|
||
></LI
|
||
></UL
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section1-devsandbox"
|
||
>Developer Sandbox</A
|
||
>
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-clockinsync"
|
||
>Keep System clocks in Sync</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-dontshare"
|
||
>Do not share the sandbox</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-syncup"
|
||
>Stay in sync with the repository</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-workinside"
|
||
>Do not work outside the sandbox</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-cleanupatcompletion"
|
||
>Cleanup after Completion</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-checkin"
|
||
>Check-in Often</A
|
||
>
|
||
</P
|
||
></LI
|
||
></UL
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section1-serverconfig"
|
||
>CVS Server Configuration</A
|
||
>
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-accesscontrol"
|
||
>CVS access control</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-scripting"
|
||
>Server side scripting</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-notification"
|
||
>Server Notification</A
|
||
>
|
||
</P
|
||
></LI
|
||
></UL
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section1-branchmerge"
|
||
>Branching and Merging</A
|
||
>
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-branchowner"
|
||
>Assign ownership to Trunk and Branches</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-tagrelease"
|
||
>Tag each release</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-branchatrelease"
|
||
>Create a branch after each release</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-bugfixbranches"
|
||
>Make bug fixes to branches only</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-patchesfrombranches"
|
||
>Make patch releases from branches only</A
|
||
>
|
||
</P
|
||
></LI
|
||
></UL
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section1-chgpropagation"
|
||
>Change Propagation</A
|
||
>
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-mergebugfix"
|
||
>Merge branch with the trunk after release</A
|
||
>
|
||
</P
|
||
></LI
|
||
></UL
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section1-softwarebuild"
|
||
>Software Builds</A
|
||
>
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-bebo"
|
||
>Build Early and Build Often</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-automate"
|
||
>Automate build Process completely</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-ensurecheckin"
|
||
>All necessary files must be checked-in before build</A
|
||
>
|
||
</P
|
||
></LI
|
||
></UL
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section1-instprocess"
|
||
>Institutionalize CVS in the Organization</A
|
||
>
|
||
</P
|
||
><P
|
||
></P
|
||
><UL
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-chngmgmt"
|
||
>Implement Change Management Process</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-objectives"
|
||
>Make CVS Usage part of Objectives</A
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-metrics"
|
||
>Collect metrics on CVS usage</A
|
||
>
|
||
</P
|
||
></LI
|
||
></UL
|
||
></LI
|
||
></OL
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-guitools"
|
||
></A
|
||
>3. Using <SPAN
|
||
CLASS="acronym"
|
||
>GUI</SPAN
|
||
> Tools</H1
|
||
><P
|
||
>The traditional interface available for CVS is the command-line client.
|
||
There has also been a slew of GUI client applications that can
|
||
<SPAN
|
||
CLASS="QUOTE"
|
||
>"talk"</SPAN
|
||
> to a CVS server. These GUI clients provide a
|
||
<SPAN
|
||
CLASS="QUOTE"
|
||
>"point and click"</SPAN
|
||
> interface to the CVS repository.
|
||
</P
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-useguiclient"
|
||
></A
|
||
>3.1. Use GUI CVS client</H2
|
||
><P
|
||
> This paper recommends using such GUI clients during the initial
|
||
deployment of CVS in an organization.</P
|
||
><P
|
||
>Developers typically use integrated development environments that have
|
||
the CM tools integrated into them. These tools minimize the learning for the
|
||
developers about the intricacies of CVS usage and instead allow them to be
|
||
productive from day one. Developers who are accustomed to other CM tools will
|
||
find the CVS command-line interface daunting. The adoption and usage of
|
||
CVS can be improved by using GUI tools for CVS clients. </P
|
||
><P
|
||
> GUI tools for CVS are available at <A
|
||
HREF="http://cvsgui.sourceforge.net/"
|
||
TARGET="_top"
|
||
>http://cvsgui.sourceforge.net/</A
|
||
>.
|
||
GUI interfaces are available for most of the popular platforms (Windows, Mac
|
||
and Linux). In addition, on the Windows platform there is an
|
||
<SPAN
|
||
CLASS="acronym"
|
||
>SCC</SPAN
|
||
> extension that allows integration of CVS as the
|
||
configuration control tool with popular IDE.</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-devsandbox"
|
||
></A
|
||
>4. Developer Sandbox</H1
|
||
><P
|
||
>The developer <SPAN
|
||
CLASS="QUOTE"
|
||
>"sandbox"</SPAN
|
||
> is where each developer keeps his
|
||
or her working copy of the code base. In CVS this is referred to as the
|
||
working directory. This is where they build, test and debug the modules that
|
||
they are working on. A sandbox can also be the area where the staging build
|
||
or the production build is done. Changes made in the work area are checked
|
||
into the CVS repository. In addition, changes made in the repository by
|
||
others have to be updated in the sandbox on a regular basis. </P
|
||
><P
|
||
>The best practices related to developers sandbox are:
|
||
</P
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-clockinsync"
|
||
></A
|
||
>4.1. Keep System clocks in Sync</H2
|
||
><P
|
||
>CVS tracks change to source files by using the timestamp on the
|
||
file. If each client system date and time is not in sync, there is a
|
||
definite possibility of CVS getting confused. Thus system clocks must be
|
||
kept in sync by use of a central time server or similar mechanism.
|
||
</P
|
||
><P
|
||
>CVS is designed from ground up to handle multiple timezones. As
|
||
long as the host operating system has been setup and configured correctly,
|
||
CVS will be able to track changes correctly.
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-dontshare"
|
||
></A
|
||
>4.2. Do not share the sandbox</H2
|
||
><P
|
||
>Sandboxes have to be unique for each developer or purpose. They
|
||
should not be used for multiple things at the same time. A sandbox can be a
|
||
working area for a developer or the build area for the final release. If
|
||
such sandboxes are shared, then the owner of the sandbox will not be aware
|
||
of the changes made to the files resulting in confusion. </P
|
||
><P
|
||
>In CVS, the sandbox is created automatically when a working copy is
|
||
checked out for a CVS project using the <B
|
||
CLASS="command"
|
||
>cvs checkout
|
||
{project-name}</B
|
||
> command. </P
|
||
><P
|
||
>In very large projects, it does not make sense for the developers to
|
||
check-out the entire source into the local sandbox. In such cases, they can
|
||
take the binaries generated by the build team on a regular basis for all those
|
||
components of the application that is not changed by them and only check-out
|
||
the parts that are built by the developer. </P
|
||
><P
|
||
>For example, in a Java project, the build team can keep the results of
|
||
their last successful build in a standard location in the form of JAR files on
|
||
the network file servers. Individual developers will use a standard classpath
|
||
setup that has the network drives mounted on standard paths. Thus, the
|
||
developers will automatically get the latest version of the files as required
|
||
by them.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-syncup"
|
||
></A
|
||
>4.3. Stay in sync with the repository</H2
|
||
><P
|
||
>To gain the benefits of working within a sandbox as mentioned above,
|
||
the developer must keep his or her sandbox in sync with the main repository.
|
||
A regular <B
|
||
CLASS="command"
|
||
>cvs update</B
|
||
> with the appropriate tag or branch
|
||
name will ensure that the sandboxes are kept up to date. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-workinside"
|
||
></A
|
||
>4.4. Do not work outside the sandbox</H2
|
||
><P
|
||
>The sandbox can be thought of as a controlled area within which CVS
|
||
can track for changes made to the various source files. Files belonging to
|
||
other developers will be automatically updated by CVS in the developer's
|
||
sandbox. Thus the developer who lives within the sandbox will stand to gain
|
||
a lot of benefits of concurrent development. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-cleanupatcompletion"
|
||
></A
|
||
>4.5. Cleanup after Completion</H2
|
||
><P
|
||
>Make sure that the sandbox is cleaned up after completion of work on
|
||
the files. Cleanup can be done in CVS by using the <B
|
||
CLASS="command"
|
||
>cvs
|
||
release</B
|
||
> command. This ensures that no old version of the files
|
||
exists in the development sandbox. As explained previously, pre-built
|
||
binaries from the build team can be used to ensure that all the parts of the
|
||
application are available to the developer without the need for a complete
|
||
compilation in the sandbox. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-checkin"
|
||
></A
|
||
>4.6. Check-in Often</H2
|
||
><P
|
||
>To help other developers keep their code in sync with your code, you
|
||
must check-in your code often into the CVS repository. The best
|
||
practice would be to check-in soon as a piece of code is completed, reviewed
|
||
and tested, check-in the changes with <B
|
||
CLASS="command"
|
||
>cvs commit</B
|
||
> to
|
||
ensure that your changes are committed to the CVS repository. </P
|
||
><P
|
||
> CVS promotes concurrent development. Concurrent development is
|
||
possible only if all the other developers are aware of the ongoing changes
|
||
on a regular basis. This awareness can be termed as <SPAN
|
||
CLASS="QUOTE"
|
||
>"situation
|
||
awareness"</SPAN
|
||
> </P
|
||
><DIV
|
||
CLASS="warning"
|
||
><P
|
||
></P
|
||
><TABLE
|
||
CLASS="warning"
|
||
WIDTH="100%"
|
||
BORDER="0"
|
||
><TR
|
||
><TD
|
||
WIDTH="25"
|
||
ALIGN="CENTER"
|
||
VALIGN="TOP"
|
||
><IMG
|
||
SRC="../images/warning.gif"
|
||
HSPACE="5"
|
||
ALT="Warning"></TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
VALIGN="TOP"
|
||
><P
|
||
>One of the <SPAN
|
||
CLASS="QUOTE"
|
||
>"bad"</SPAN
|
||
> practices that commonly occur
|
||
is the sharing of files between developers by email. This works against
|
||
most of the best practices mentioned above. To share updates between two
|
||
developers, CVS must be used as the communication medium. This will
|
||
ensure that CVS is <SPAN
|
||
CLASS="QUOTE"
|
||
>"aware"</SPAN
|
||
> of the changes and can track
|
||
them. Thus, audit trail can be established if necessary. </P
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
></DIV
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-serverconfig"
|
||
></A
|
||
>5. CVS Server Configuration</H1
|
||
><P
|
||
>This section deals with best practices for CVS server side setup and
|
||
configuration.
|
||
</P
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-accesscontrol"
|
||
></A
|
||
>5.1. CVS access control</H2
|
||
><P
|
||
>One of the important questions that I have been asked time and again is the
|
||
ability to have access control for files/folders/branches etc., within
|
||
the CVS repository for various users. Unfortunately CVS does not
|
||
come with a built in Access control capability but it does support a
|
||
rudimentary form of access control through the readers/writers files in
|
||
the CVSROOT repository. I have put together a set of scripts that use
|
||
the readers/writers files to provide a slightly useable version of access
|
||
control. This is available at <A
|
||
HREF="http://cvspermissions.sarovar.org"
|
||
TARGET="_top"
|
||
>http://cvspermissions.sarovar.org</A
|
||
>
|
||
as an Open Source project. Feel free to use it and let me know how it
|
||
works for you. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-scripting"
|
||
></A
|
||
>5.2. Server side scripting</H2
|
||
><P
|
||
>Server side scripting refers to the ability to make CVS server
|
||
execute certain scripts when an event occurs. A common script that
|
||
helps is to verify that all cvs commits contain acomment entered by the
|
||
developer. The process involves setting up the
|
||
<TT
|
||
CLASS="filename"
|
||
>CVSROOT/verifymsg</TT
|
||
> file to run a script when a file is
|
||
checked-in. </P
|
||
><TABLE
|
||
BORDER="0"
|
||
BGCOLOR="#E0E0E0"
|
||
WIDTH="100%"
|
||
><TR
|
||
><TD
|
||
><FONT
|
||
COLOR="#000000"
|
||
><PRE
|
||
CLASS="programlisting"
|
||
> ------CVSROOT/verifymsg---------
|
||
|
||
#Set the verifymsg file to fire a script
|
||
DEFAULT /usr/local/bin/validate-cvs-log.sh
|
||
|
||
|
||
------/usr/local/bin/validate-cvs-log.sh ---------
|
||
|
||
#!/bin/sh
|
||
#
|
||
# validate-cvs-log.sh logfile
|
||
|
||
# test that log message has some characters in it
|
||
if [ `cat $1 | wc -c ` -lt 10 ] ; then
|
||
echo "log message too short; please enter a description for the changes"
|
||
exit 1
|
||
else
|
||
exit 0
|
||
fi
|
||
</PRE
|
||
></FONT
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-notification"
|
||
></A
|
||
>5.3. Server Notification</H2
|
||
><P
|
||
>The CVS server can be configured to notify through e-mails in case
|
||
of a commit happening. This can be used to verify whether commits are
|
||
occurring during the course of a daily/release build. If such commits
|
||
occur, based on the project policy, the commits can be ignored or the entire
|
||
build automatically restarted.</P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-branchmerge"
|
||
></A
|
||
>6. Branching and Merging</H1
|
||
><P
|
||
> Branching in CVS splits a project's development into separate,
|
||
parallel histories. Changes made on one branch do not affect the other
|
||
branches. Branching can be used extensively to maintain multiple versions
|
||
of a product for providing support and new features. </P
|
||
><P
|
||
> Merging converges the branches back to the main trunk. In a merge,
|
||
CVS calculates the changes made on the branch between the point where it
|
||
diverged from the trunk and the branch's tip (its most recent state), then
|
||
applies those differences to the project at the tip of the trunk. </P
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-branchowner"
|
||
></A
|
||
>6.1. Assign ownership to Trunk and Branches</H2
|
||
><P
|
||
>The main trunk of the source tree and the various branches should have a
|
||
owner assigned who will be responsible for. </P
|
||
><P
|
||
></P
|
||
><OL
|
||
TYPE="1"
|
||
><LI
|
||
><P
|
||
>Keep the list of configurable items for the branch or trunk.
|
||
</P
|
||
><P
|
||
>The owner will be the maintainer of the contents list for the branch or
|
||
trunk. This list should contain the item name and a brief description about
|
||
the item. This list is essential since new artifacts are always added to or
|
||
removed from the repository on an ongoing basis. This list will be able to
|
||
track the new additions/deletions to the repository for the respective branch.
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Establish a working policy for the branch or trunk.
|
||
</P
|
||
><P
|
||
>The owner will establish policies for check-in and check-out. The
|
||
policy will define when the code can be checked in (after coding or after
|
||
review etc.,). Who is responsible to merge changes on the same file and
|
||
resolve conflicts (the author or the person who recently changed the file).
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Identify and document policy deviations
|
||
</P
|
||
><P
|
||
>Policies once established tend to have exceptions. The owner will be
|
||
responsible for identifying the workaround and tracking/documenting the same
|
||
for future use. </P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Responsible for merge with the trunk
|
||
</P
|
||
><P
|
||
>The branch owner will be responsible for ensuring that the changes in
|
||
the branch can be successfully merged with the main trunk at a reasonable point
|
||
in time. </P
|
||
></LI
|
||
></OL
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-tagrelease"
|
||
></A
|
||
>6.2. Tag each release</H2
|
||
><P
|
||
>As part of the release process, the entire code base must be tagged with an
|
||
identifier that can help in uniquely identifying the release. A tag gives a
|
||
label to the collection of revisions represented by one developer's working
|
||
copy (usually, that working copy is completely up to date so the tag name is
|
||
attached to the <SPAN
|
||
CLASS="QUOTE"
|
||
>"latest and greatest"</SPAN
|
||
> revisions in the
|
||
repository). </P
|
||
><P
|
||
>The identifier for the tag should provide enough information to
|
||
identify the release at any point in time in the future. One suggested tag
|
||
identifier is of the form. </P
|
||
><P
|
||
CLASS="literallayout"
|
||
><br>
|
||
<TT
|
||
CLASS="literal"
|
||
>release_</TT
|
||
>{major version #}_{minor version #}<br>
|
||
</P
|
||
><DIV
|
||
CLASS="note"
|
||
><P
|
||
></P
|
||
><TABLE
|
||
CLASS="note"
|
||
WIDTH="100%"
|
||
BORDER="0"
|
||
><TR
|
||
><TD
|
||
WIDTH="25"
|
||
ALIGN="CENTER"
|
||
VALIGN="TOP"
|
||
><IMG
|
||
SRC="../images/note.gif"
|
||
HSPACE="5"
|
||
ALT="Note"></TD
|
||
><TD
|
||
ALIGN="LEFT"
|
||
VALIGN="TOP"
|
||
><P
|
||
>As one reader pointed out to me, a good practice here is to tag
|
||
the release first. Checkout the entire codebase using the tag, and then
|
||
proceed to go through a build / deploy / test process before making the
|
||
actual release. This will absolutely ensure that what <SPAN
|
||
CLASS="QUOTE"
|
||
>"leaves the
|
||
door "</SPAN
|
||
> is a verified and tested codebase.</P
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-branchatrelease"
|
||
></A
|
||
>6.3. Create a branch after each release</H2
|
||
><P
|
||
>After each software release, once the CVS repository is tagged, a
|
||
branch has to be immediately created. This branch will serve as the bug fix
|
||
baseline for that release. This branch is created only if the release is
|
||
not a bug fix or patch release in the first place. Patches that have to be
|
||
made for this release at any point in time in the future will be developed
|
||
on this branch. The main trunk will be used for ongoing product
|
||
development. </P
|
||
><P
|
||
>With this arrangement, the changes in the code for the ongoing
|
||
development will be on the main trunk and the branch will provide a separate
|
||
partition for hot fixes and bug fix releases. </P
|
||
><P
|
||
>The identifier for the branch name can be of the form. </P
|
||
><P
|
||
CLASS="literallayout"
|
||
><br>
|
||
<TT
|
||
CLASS="literal"
|
||
>release_</TT
|
||
>{major version #}_{minor version #}<TT
|
||
CLASS="literal"
|
||
>_patches</TT
|
||
><br>
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-bugfixbranches"
|
||
></A
|
||
>6.4. Make bug fixes to branches only</H2
|
||
><P
|
||
>This practice extends from the previous practice of creating a
|
||
separate branch after a major release. The branch will serve as the code
|
||
base for all bug fixes and patch release that have to be made. Thus, there
|
||
is a separate repository <SPAN
|
||
CLASS="QUOTE"
|
||
>"sandbox"</SPAN
|
||
> where the hot fixes and
|
||
patches can be developed apart from the mainstream development. </P
|
||
><P
|
||
>This practice also ensures that bug fixes done to previous releases do
|
||
not mysteriously affect the mainstream version. In addition, new features
|
||
added to the mainstream version do not creep into the patch release
|
||
accidentally. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-patchesfrombranches"
|
||
></A
|
||
>6.5. Make patch releases from branches only</H2
|
||
><P
|
||
>Since all the bug fixes for a given release are done on its
|
||
corresponding branch, the patch releases are made from the branch. This
|
||
ensures that there is no confusion on the feature set that is released as
|
||
part of the patch release. </P
|
||
><P
|
||
>After the patch release is made, the branch has to be tagged using the
|
||
release tagging practice (see <A
|
||
HREF="#section2-tagrelease"
|
||
>Tag each release</A
|
||
>). </P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-chgpropagation"
|
||
></A
|
||
>7. Change Propagation</H1
|
||
><P
|
||
>Change propagation practices explore how changes made to one version of
|
||
the application are migrated to other living versions of the application.
|
||
</P
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-mergebugfix"
|
||
></A
|
||
>7.1. Merge branch with the trunk after release</H2
|
||
><P
|
||
>After each release from a branch, the changes made to the branch
|
||
should be merged with the trunk. This ensures that all the bug fixes made
|
||
to the patch release are properly incorporated into future releases of the
|
||
application. </P
|
||
><P
|
||
>This merge could potentially be time consuming depending on the amount
|
||
of changes made to the trunk and the branch being merged. In fact, it will
|
||
probably result in a lot of conflicts in CVS resulting in manual merges.
|
||
After the merge, the trunk code base must be tested to verify that the
|
||
application is in proper working order. This must be kept in mind while
|
||
preparing the project schedule. </P
|
||
><P
|
||
>In the case of changes occurring on branches for a long period,
|
||
these changes can be merged to the main branch on a regular basis even
|
||
before the release is made. The frequency of merge is done based on certain
|
||
logical points in the branch's evolution. To ensure that duplicate merging
|
||
does not occur, the following practice can be adopted. </P
|
||
><P
|
||
>In addition to the branch tag, a tag called {branch_name}_MERGED
|
||
should be created. This is initially at the same level as the last release
|
||
tag for the branch. This tag is then <SPAN
|
||
CLASS="QUOTE"
|
||
>"moved"</SPAN
|
||
> after each
|
||
intermediate merge by using the <B
|
||
CLASS="command"
|
||
>-F</B
|
||
> option. This
|
||
eliminates duplicate merging issues during intermediate merges. </P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-softwarebuild"
|
||
></A
|
||
>8. Software Builds</H1
|
||
><P
|
||
>This section deals with the best practices for software builds. Build
|
||
is the process of creating the application binaries for a software release.
|
||
They are done in a periodic manner by the build teams to provide baseline
|
||
binaries for daily work. </P
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-bebo"
|
||
></A
|
||
>8.1. Build Early and Build Often (<SPAN
|
||
CLASS="acronym"
|
||
>BEBO</SPAN
|
||
>)</H2
|
||
><P
|
||
>A variation of this adage has been around in the Open Source
|
||
community called "Release Early and Release Often" for quite some time
|
||
albeit for a different reason. BEBO helps a development team identify
|
||
issues that can arise from checking in the wrong files. BEBO will address
|
||
integration issues at the application level that might have slipped passed
|
||
individual developer builds. It will also improve the team morale when they
|
||
see a working version of the application.</P
|
||
><P
|
||
>Builds must be done on a regular basis. There should be a dedicated
|
||
resource(s) assigned to do the same. The entire project team must be
|
||
trained to view the daily build as an important activity and not as a chore.
|
||
Builds must be completed without any failures on a regular basis. Build
|
||
failures must be a rare event and should be treated with utmost seriousness.
|
||
The project team should ensure that successful builds are top priority on
|
||
their agenda. The seriousness can be emphasised by setting up a penalty for
|
||
breaking the build. </P
|
||
><P
|
||
>Each build can be tagged in CVS using a standard naming convention.
|
||
This can help developers checkout a working version of the entire system
|
||
from daily builds for local development. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-automate"
|
||
></A
|
||
>8.2. Automate build Process completely</H2
|
||
><P
|
||
>Another key practice for software builds is to automate the build
|
||
process completely. The automation process must also include automatic
|
||
retrieval of the right source files from the CVS repository. This
|
||
ensures that the build process is completely repeatable and consistent. In
|
||
addition, the chances of a build with the wrong version of the application
|
||
source files are reduced to a large degree. </P
|
||
><P
|
||
>By automating the build process, the task of building often becomes
|
||
less burdensome. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-ensurecheckin"
|
||
></A
|
||
>8.3. All necessary files must be checked-in before build</H2
|
||
><P
|
||
>This adage sounds trivial at first but this problem is very common
|
||
even with experienced development teams due to oversight. The problem of
|
||
oversight cannot be easily addressed since the onus is on the individual
|
||
developer to ensure that his or her file has been checked in. This practice
|
||
should be drummed into the team in the form of training and pre-build
|
||
announcements to ensure that the right version of source code is available
|
||
in the repository. </P
|
||
><P
|
||
>Automated build process as explained above will help in catching this
|
||
problem to a certain degree since they will automatically take the source
|
||
code from the CVS repository and perform the software build. Any missed
|
||
items will surface during the build process itself (makefiles etc.,) or
|
||
during the regression testing of the product (older version of the file
|
||
checked in). </P
|
||
><P
|
||
>A penalty based system can be setup to handle wrong check-in. Having a
|
||
kitty for a post project party to which each person who makes a wrong check-in
|
||
will contribute a fixed amount will act a good penalty system. </P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-instprocess"
|
||
></A
|
||
>9. Institutionalize CVS in the Organization</H1
|
||
><P
|
||
>Here we will look at the best practices for institutionalizing CVS
|
||
usage in the organization.
|
||
</P
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-chngmgmt"
|
||
></A
|
||
>9.1. Implement Change Management Process</H2
|
||
><P
|
||
>All organizations must implement a good Change management process
|
||
(<SPAN
|
||
CLASS="acronym"
|
||
>CMP</SPAN
|
||
>). A good CMP will define how changes are received,
|
||
recorded, tracked, executed and delivered. CVS provides version
|
||
control for your project. Change management addresses the <SPAN
|
||
CLASS="QUOTE"
|
||
>"bigger
|
||
picture"</SPAN
|
||
> of how enhancements and bugs are received, tracked and
|
||
closed. CVS will play a smaller but a very important part in this
|
||
entire picture. With a formal change management process in place in the
|
||
organization, tools such as CVS will be looked at as aiding this process
|
||
instead of acting as a general development overhead. </P
|
||
><P
|
||
>Change management is quite a vast topic that cannot be done justice
|
||
here. Please look up other sources of information on change management. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-objectives"
|
||
></A
|
||
>9.2. Make CVS Usage part of Objectives</H2
|
||
><P
|
||
>To institutionalize CVS, it can be made as part of the performance
|
||
objectives for the developer to use CVS in the project. In addition, it
|
||
can also be made as part of the objective for the project manager to deploy
|
||
CVS in his or her project. </P
|
||
><P
|
||
>Compliance of this can then be reviewed as part of the appraisal cycle
|
||
for the employee. </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-metrics"
|
||
></A
|
||
>9.3. Collect metrics on CVS usage</H2
|
||
><P
|
||
>CVS usage metrics can be collected in terms of percentage of
|
||
deployment in the organization, project size handled etc., This information
|
||
will spur other line managers and program managers to look at CVS as a
|
||
tool that will aid them in their daily operations. </P
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-inaction"
|
||
></A
|
||
>10. Best Practices in Action</H1
|
||
><P
|
||
>The best way to explain the need for these best practices is by
|
||
putting together an example of a real world project scenario and show how
|
||
exactly will these best practices fit into the <SPAN
|
||
CLASS="QUOTE"
|
||
>"bigger
|
||
picture"</SPAN
|
||
>. Also, a lot of readers have told me that the sections on
|
||
<A
|
||
HREF="#section1-branchmerge"
|
||
>Branching and Merging</A
|
||
>
|
||
and <A
|
||
HREF="#section1-chgpropagation"
|
||
>Change Propagation</A
|
||
> will require examples for better
|
||
explanation. Listening to the readers is a Good Thing so I have
|
||
put together a particular project scenario and then create a series of
|
||
events to show how the best practices, if followed, would help is making
|
||
operations smoother. </P
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-inception"
|
||
></A
|
||
>10.1. Inception</H2
|
||
><P
|
||
>Consider a software project where version 1.0 has just been put into
|
||
production and everyone is done celebrating. The next step is to start
|
||
working on the new features of the subsequent release. Also, the users of
|
||
the system have started to use it full-time and bug reports of various
|
||
levels have started to come in. </P
|
||
><P
|
||
> Before jumping into new enhancements or bug fixes, the best practices
|
||
for <A
|
||
HREF="#section1-branchmerge"
|
||
>Branching and Merging</A
|
||
> should be followed. Few of
|
||
the important practices are <A
|
||
HREF="#section2-tagrelease"
|
||
>Tag each release</A
|
||
> and
|
||
<A
|
||
HREF="#section2-branchatrelease"
|
||
>Create a branch after each release</A
|
||
>. These practices will
|
||
effectively established two <SPAN
|
||
CLASS="QUOTE"
|
||
>"development environments"</SPAN
|
||
>,
|
||
one for regular enhancements and the other for bug fixes and minor
|
||
enhancements on the last release.</P
|
||
><P
|
||
>Let us assume that the release was tagged as
|
||
<P
|
||
CLASS="literallayout"
|
||
><br>
|
||
<TT
|
||
CLASS="literal"
|
||
>release_1_0</TT
|
||
><br>
|
||
</P
|
||
>
|
||
</P
|
||
><P
|
||
>Then the branch was created with the branch name
|
||
<P
|
||
CLASS="literallayout"
|
||
><br>
|
||
<TT
|
||
CLASS="literal"
|
||
>release_1_0_patches</TT
|
||
><br>
|
||
</P
|
||
>
|
||
</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect2"
|
||
><HR><H2
|
||
CLASS="sect2"
|
||
><A
|
||
NAME="section2-dand"
|
||
></A
|
||
>10.2. Development and Delivery</H2
|
||
><P
|
||
>Now, we are ready for business. Let us examine the bug fixes and
|
||
enhancements track. Assume that there are three bugs of which two are of a
|
||
high priority that should be fixed right away (possibly within a week) and the
|
||
third can be delivered after some time (say after 4 weeks). In the
|
||
middle of this schedule there is a regular release scheduled in three weeks.
|
||
Considering that we have a busy month ahead, let us see how exactly we can
|
||
use the Best practices to ease the days ahead.</P
|
||
><P
|
||
>The timeline for the various release in the next month looks like this.
|
||
</P
|
||
><TABLE
|
||
BORDER="0"
|
||
BGCOLOR="#E0E0E0"
|
||
WIDTH="100%"
|
||
><TR
|
||
><TD
|
||
><FONT
|
||
COLOR="#000000"
|
||
><PRE
|
||
CLASS="programlisting"
|
||
> Fix Enhancement Fix
|
||
Today Release 1 Release Release 2
|
||
|_______|______________|_________|
|
||
Time -->
|
||
</PRE
|
||
></FONT
|
||
></TD
|
||
></TR
|
||
></TABLE
|
||
><P
|
||
>We have two teams, one working on the bug fix branch and another team
|
||
working on the features for the next release on the main trunk. These
|
||
teams must make sure that they start out with the right version in
|
||
their sandbox.</P
|
||
><P
|
||
></P
|
||
><OL
|
||
TYPE="1"
|
||
><LI
|
||
><P
|
||
> The bug fix team will check out using the command line
|
||
</P
|
||
><P
|
||
> <B
|
||
CLASS="command"
|
||
>cvs checkout -R -r release_1_0_patches {project name}</B
|
||
>
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>The team that is working on the next release will use the command line
|
||
</P
|
||
><P
|
||
> <B
|
||
CLASS="command"
|
||
>cvs checkout -R {project name}</B
|
||
>
|
||
</P
|
||
></LI
|
||
></OL
|
||
><P
|
||
> As soon as the bug fix team completes the two top priority bugs, they
|
||
will update, verify a successful build and commit their changes to the bug
|
||
fix branch using the command line
|
||
</P
|
||
><B
|
||
CLASS="command"
|
||
> cvs update -R -r release_1_0_patches {module name}
|
||
</B
|
||
><P
|
||
>The team should perform a build at this point to verify that the
|
||
update did not break any code on the branch. Once the build is successful,
|
||
the branch should be committed back into the repository. </P
|
||
><B
|
||
CLASS="command"
|
||
> cvs commit -R -r release_1_0_patches {module name}
|
||
</B
|
||
><P
|
||
><A
|
||
HREF="#section2-bebo"
|
||
>Build Early and Build Often</A
|
||
> : On a daily basis, each developer
|
||
will check in code to CVS and to ensure sanity of code, daily builds on
|
||
the bug fixed branch will be undertaken by checking out from
|
||
CVS on a clean environment and completely rebuilt. These daily builds
|
||
can be tagged in CVS using the following naming convention </P
|
||
><P
|
||
CLASS="literallayout"
|
||
><br>
|
||
<TT
|
||
CLASS="literal"
|
||
>build_1_1_yyyymmdd : for the branch</TT
|
||
><br>
|
||
<TT
|
||
CLASS="literal"
|
||
>build_2_0_yyyymmdd : for the trunk</TT
|
||
><br>
|
||
</P
|
||
><P
|
||
>The regular process of build-test-fix is followed to make a version
|
||
ready for delivery. The tag will help developers checkout a working copy of
|
||
the latest build as and when necessary. </P
|
||
><P
|
||
> When the source code is released to the outside world, two practices
|
||
have to be followed. </P
|
||
><P
|
||
></P
|
||
><OL
|
||
TYPE="1"
|
||
><LI
|
||
><P
|
||
> <A
|
||
HREF="#section2-tagrelease"
|
||
>Tag each release</A
|
||
> : This ensures that the bug fix
|
||
release is tagged correctly and so can be traced out at a later point in
|
||
time if necessary.
|
||
</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
><A
|
||
HREF="#section2-mergebugfix"
|
||
>Merge branch with the trunk after release</A
|
||
> : This ensures that the bug fix
|
||
is merged back into the main trunk ensuring that all future
|
||
releases is a truly cumulative delivery.
|
||
</P
|
||
></LI
|
||
></OL
|
||
></DIV
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="section1-conclusion"
|
||
></A
|
||
>11. Conclusion</H1
|
||
><P
|
||
>These best practices are meant to help software teams get a head start
|
||
on using CVS for their development. The ideas presented here have to be
|
||
constantly reviewed and evolved. I would like this to be a growing and
|
||
evolving document. Please send your comments and ideas to
|
||
<TT
|
||
CLASS="email"
|
||
><<A
|
||
HREF="mailto:vivekv at yahoo dot com"
|
||
>vivekv at yahoo dot com</A
|
||
>></TT
|
||
> </P
|
||
></DIV
|
||
><DIV
|
||
CLASS="appendix"
|
||
><HR><H1
|
||
CLASS="appendix"
|
||
><A
|
||
NAME="gfdl"
|
||
></A
|
||
>A. GNU Free Documentation License</H1
|
||
><P
|
||
>Version 1.1, March 2000</P
|
||
><A
|
||
NAME="AEN433"
|
||
></A
|
||
><BLOCKQUOTE
|
||
CLASS="BLOCKQUOTE"
|
||
><P
|
||
>Copyright (C) 2000 Free Software Foundation, Inc.
|
||
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
||
Everyone is permitted to copy and distribute verbatim copies
|
||
of this license document, but changing it is not allowed.</P
|
||
></BLOCKQUOTE
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN435"
|
||
></A
|
||
>0. Preamble</H1
|
||
><P
|
||
>The purpose of this License is to make a manual, textbook,
|
||
or other written document "free" in the sense of freedom: to
|
||
assure everyone the effective freedom to copy and redistribute it,
|
||
with or without modifying it, either commercially or
|
||
noncommercially. Secondarily, this License preserves for the
|
||
author and publisher a way to get credit for their work, while not
|
||
being considered responsible for modifications made by
|
||
others.</P
|
||
><P
|
||
>This License is a kind of "copyleft", which means that
|
||
derivative works of the document must themselves be free in the
|
||
same sense. It complements the GNU General Public License, which
|
||
is a copyleft license designed for free software.</P
|
||
><P
|
||
>We have designed this License in order to use it for manuals
|
||
for free software, because free software needs free documentation:
|
||
a free program should come with manuals providing the same
|
||
freedoms that the software does. But this License is not limited
|
||
to software manuals; it can be used for any textual work,
|
||
regardless of subject matter or whether it is published as a
|
||
printed book. We recommend this License principally for works
|
||
whose purpose is instruction or reference.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN440"
|
||
></A
|
||
>1. Applicability and Definitions</H1
|
||
><P
|
||
>This License applies to any manual or other work that
|
||
contains a notice placed by the copyright holder saying it can be
|
||
distributed under the terms of this License. The "Document",
|
||
below, refers to any such manual or work. Any member of the
|
||
public is a licensee, and is addressed as "you".</P
|
||
><P
|
||
>A "Modified Version" of the Document means any work
|
||
containing the Document or a portion of it, either copied
|
||
verbatim, or with modifications and/or translated into another
|
||
language.</P
|
||
><P
|
||
>A "Secondary Section" is a named appendix or a front-matter
|
||
section of the Document that deals exclusively with the
|
||
relationship of the publishers or authors of the Document to the
|
||
Document's overall subject (or to related matters) and contains
|
||
nothing that could fall directly within that overall subject.
|
||
(For example, if the Document is in part a textbook of
|
||
mathematics, a Secondary Section may not explain any mathematics.)
|
||
The relationship could be a matter of historical connection with
|
||
the subject or with related matters, or of legal, commercial,
|
||
philosophical, ethical or political position regarding
|
||
them.</P
|
||
><P
|
||
>The "Invariant Sections" are certain Secondary Sections
|
||
whose titles are designated, as being those of Invariant Sections,
|
||
in the notice that says that the Document is released under this
|
||
License.</P
|
||
><P
|
||
>The "Cover Texts" are certain short passages of text that
|
||
are listed, as Front-Cover Texts or Back-Cover Texts, in the
|
||
notice that says that the Document is released under this
|
||
License.</P
|
||
><P
|
||
>A "Transparent" copy of the Document means a
|
||
machine-readable copy, represented in a format whose specification
|
||
is available to the general public, whose contents can be viewed
|
||
and edited directly and straightforwardly with generic text
|
||
editors or (for images composed of pixels) generic paint programs
|
||
or (for drawings) some widely available drawing editor, and that
|
||
is suitable for input to text formatters or for automatic
|
||
translation to a variety of formats suitable for input to text
|
||
formatters. A copy made in an otherwise Transparent file format
|
||
whose markup has been designed to thwart or discourage subsequent
|
||
modification by readers is not Transparent. A copy that is not
|
||
"Transparent" is called "Opaque".</P
|
||
><P
|
||
>Examples of suitable formats for Transparent copies include
|
||
plain ASCII without markup, Texinfo input format, LaTeX input
|
||
format, SGML or XML using a publicly available DTD, and
|
||
standard-conforming simple HTML designed for human modification.
|
||
Opaque formats include PostScript, PDF, proprietary formats that
|
||
can be read and edited only by proprietary word processors, SGML
|
||
or XML for which the DTD and/or processing tools are not generally
|
||
available, and the machine-generated HTML produced by some word
|
||
processors for output purposes only.</P
|
||
><P
|
||
>The "Title Page" means, for a printed book, the title page
|
||
itself, plus such following pages as are needed to hold, legibly,
|
||
the material this License requires to appear in the title page.
|
||
For works in formats which do not have any title page as such,
|
||
"Title Page" means the text near the most prominent appearance of
|
||
the work's title, preceding the beginning of the body of the
|
||
text.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN450"
|
||
></A
|
||
>2. Verbatim Copying</H1
|
||
><P
|
||
>You may copy and distribute the Document in any medium,
|
||
either commercially or noncommercially, provided that this
|
||
License, the copyright notices, and the license notice saying this
|
||
License applies to the Document are reproduced in all copies, and
|
||
that you add no other conditions whatsoever to those of this
|
||
License. You may not use technical measures to obstruct or
|
||
control the reading or further copying of the copies you make or
|
||
distribute. However, you may accept compensation in exchange for
|
||
copies. If you distribute a large enough number of copies you
|
||
must also follow the conditions in section 3.</P
|
||
><P
|
||
>You may also lend copies, under the same conditions stated
|
||
above, and you may publicly display copies.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN454"
|
||
></A
|
||
>3. Copying in Quantity</H1
|
||
><P
|
||
>If you publish printed copies of the Document numbering more
|
||
than 100, and the Document's license notice requires Cover Texts,
|
||
you must enclose the copies in covers that carry, clearly and
|
||
legibly, all these Cover Texts: Front-Cover Texts on the front
|
||
cover, and Back-Cover Texts on the back cover. Both covers must
|
||
also clearly and legibly identify you as the publisher of these
|
||
copies. The front cover must present the full title with all
|
||
words of the title equally prominent and visible. You may add
|
||
other material on the covers in addition. Copying with changes
|
||
limited to the covers, as long as they preserve the title of the
|
||
Document and satisfy these conditions, can be treated as verbatim
|
||
copying in other respects.</P
|
||
><P
|
||
>If the required texts for either cover are too voluminous to
|
||
fit legibly, you should put the first ones listed (as many as fit
|
||
reasonably) on the actual cover, and continue the rest onto
|
||
adjacent pages.</P
|
||
><P
|
||
>If you publish or distribute Opaque copies of the Document
|
||
numbering more than 100, you must either include a
|
||
machine-readable Transparent copy along with each Opaque copy, or
|
||
state in or with each Opaque copy a publicly-accessible
|
||
computer-network location containing a complete Transparent copy
|
||
of the Document, free of added material, which the general
|
||
network-using public has access to download anonymously at no
|
||
charge using public-standard network protocols. If you use the
|
||
latter option, you must take reasonably prudent steps, when you
|
||
begin distribution of Opaque copies in quantity, to ensure that
|
||
this Transparent copy will remain thus accessible at the stated
|
||
location until at least one year after the last time you
|
||
distribute an Opaque copy (directly or through your agents or
|
||
retailers) of that edition to the public.</P
|
||
><P
|
||
>It is requested, but not required, that you contact the
|
||
authors of the Document well before redistributing any large
|
||
number of copies, to give them a chance to provide you with an
|
||
updated version of the Document.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN460"
|
||
></A
|
||
>4. Modifications</H1
|
||
><P
|
||
>You may copy and distribute a Modified Version of the
|
||
Document under the conditions of sections 2 and 3 above, provided
|
||
that you release the Modified Version under precisely this
|
||
License, with the Modified Version filling the role of the
|
||
Document, thus licensing distribution and modification of the
|
||
Modified Version to whoever possesses a copy of it. In addition,
|
||
you must do these things in the Modified Version:</P
|
||
><P
|
||
></P
|
||
><OL
|
||
TYPE="A"
|
||
><LI
|
||
><P
|
||
>Use in the Title Page
|
||
(and on the covers, if any) a title distinct from that of the
|
||
Document, and from those of previous versions (which should, if
|
||
there were any, be listed in the History section of the
|
||
Document). You may use the same title as a previous version if
|
||
the original publisher of that version gives permission.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>List on the Title Page,
|
||
as authors, one or more persons or entities responsible for
|
||
authorship of the modifications in the Modified Version,
|
||
together with at least five of the principal authors of the
|
||
Document (all of its principal authors, if it has less than
|
||
five).</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>State on the Title page
|
||
the name of the publisher of the Modified Version, as the
|
||
publisher.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Preserve all the
|
||
copyright notices of the Document.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Add an appropriate
|
||
copyright notice for your modifications adjacent to the other
|
||
copyright notices.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Include, immediately
|
||
after the copyright notices, a license notice giving the public
|
||
permission to use the Modified Version under the terms of this
|
||
License, in the form shown in the Addendum below.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Preserve in that license
|
||
notice the full lists of Invariant Sections and required Cover
|
||
Texts given in the Document's license notice.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Include an unaltered
|
||
copy of this License.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Preserve the section
|
||
entitled "History", and its title, and add to it an item stating
|
||
at least the title, year, new authors, and publisher of the
|
||
Modified Version as given on the Title Page. If there is no
|
||
section entitled "History" in the Document, create one stating
|
||
the title, year, authors, and publisher of the Document as given
|
||
on its Title Page, then add an item describing the Modified
|
||
Version as stated in the previous sentence.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Preserve the network
|
||
location, if any, given in the Document for public access to a
|
||
Transparent copy of the Document, and likewise the network
|
||
locations given in the Document for previous versions it was
|
||
based on. These may be placed in the "History" section. You
|
||
may omit a network location for a work that was published at
|
||
least four years before the Document itself, or if the original
|
||
publisher of the version it refers to gives permission.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>In any section entitled
|
||
"Acknowledgements" or "Dedications", preserve the section's
|
||
title, and preserve in the section all the substance and tone of
|
||
each of the contributor acknowledgements and/or dedications
|
||
given therein.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Preserve all the
|
||
Invariant Sections of the Document, unaltered in their text and
|
||
in their titles. Section numbers or the equivalent are not
|
||
considered part of the section titles.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Delete any section
|
||
entitled "Endorsements". Such a section may not be included in
|
||
the Modified Version.</P
|
||
></LI
|
||
><LI
|
||
><P
|
||
>Do not retitle any
|
||
existing section as "Endorsements" or to conflict in title with
|
||
any Invariant Section.</P
|
||
></LI
|
||
></OL
|
||
><P
|
||
>If the Modified Version includes new front-matter sections
|
||
or appendices that qualify as Secondary Sections and contain no
|
||
material copied from the Document, you may at your option
|
||
designate some or all of these sections as invariant. To do this,
|
||
add their titles to the list of Invariant Sections in the Modified
|
||
Version's license notice. These titles must be distinct from any
|
||
other section titles.</P
|
||
><P
|
||
>You may add a section entitled "Endorsements", provided it
|
||
contains nothing but endorsements of your Modified Version by
|
||
various parties--for example, statements of peer review or that
|
||
the text has been approved by an organization as the authoritative
|
||
definition of a standard.</P
|
||
><P
|
||
>You may add a passage of up to five words as a Front-Cover
|
||
Text, and a passage of up to 25 words as a Back-Cover Text, to the
|
||
end of the list of Cover Texts in the Modified Version. Only one
|
||
passage of Front-Cover Text and one of Back-Cover Text may be
|
||
added by (or through arrangements made by) any one entity. If the
|
||
Document already includes a cover text for the same cover,
|
||
previously added by you or by arrangement made by the same entity
|
||
you are acting on behalf of, you may not add another; but you may
|
||
replace the old one, on explicit permission from the previous
|
||
publisher that added the old one.</P
|
||
><P
|
||
>The author(s) and publisher(s) of the Document do not by
|
||
this License give permission to use their names for publicity for
|
||
or to assert or imply endorsement of any Modified Version.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN496"
|
||
></A
|
||
>5. Combining Documents</H1
|
||
><P
|
||
>You may combine the Document with other documents released
|
||
under this License, under the terms defined in section 4 above for
|
||
modified versions, provided that you include in the combination
|
||
all of the Invariant Sections of all of the original documents,
|
||
unmodified, and list them all as Invariant Sections of your
|
||
combined work in its license notice.</P
|
||
><P
|
||
>The combined work need only contain one copy of this
|
||
License, and multiple identical Invariant Sections may be replaced
|
||
with a single copy. If there are multiple Invariant Sections with
|
||
the same name but different contents, make the title of each such
|
||
section unique by adding at the end of it, in parentheses, the
|
||
name of the original author or publisher of that section if known,
|
||
or else a unique number. Make the same adjustment to the section
|
||
titles in the list of Invariant Sections in the license notice of
|
||
the combined work.</P
|
||
><P
|
||
>In the combination, you must combine any sections entitled
|
||
"History" in the various original documents, forming one section
|
||
entitled "History"; likewise combine any sections entitled
|
||
"Acknowledgements", and any sections entitled "Dedications". You
|
||
must delete all sections entitled "Endorsements."</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN501"
|
||
></A
|
||
>6. Collections of Documents</H1
|
||
><P
|
||
>You may make a collection consisting of the Document and
|
||
other documents released under this License, and replace the
|
||
individual copies of this License in the various documents with a
|
||
single copy that is included in the collection, provided that you
|
||
follow the rules of this License for verbatim copying of each of
|
||
the documents in all other respects.</P
|
||
><P
|
||
>You may extract a single document from such a collection,
|
||
and distribute it individually under this License, provided you
|
||
insert a copy of this License into the extracted document, and
|
||
follow this License in all other respects regarding verbatim
|
||
copying of that document.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN505"
|
||
></A
|
||
>7. Aggregation with Independent Works</H1
|
||
><P
|
||
>A compilation of the Document or its derivatives with other
|
||
separate and independent documents or works, in or on a volume of
|
||
a storage or distribution medium, does not as a whole count as a
|
||
Modified Version of the Document, provided no compilation
|
||
copyright is claimed for the compilation. Such a compilation is
|
||
called an "aggregate", and this License does not apply to the
|
||
other self-contained works thus compiled with the Document, on
|
||
account of their being thus compiled, if they are not themselves
|
||
derivative works of the Document.</P
|
||
><P
|
||
>If the Cover Text requirement of section 3 is applicable to
|
||
these copies of the Document, then if the Document is less than
|
||
one quarter of the entire aggregate, the Document's Cover Texts
|
||
may be placed on covers that surround only the Document within the
|
||
aggregate. Otherwise they must appear on covers around the whole
|
||
aggregate.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN509"
|
||
></A
|
||
>8. Translation</H1
|
||
><P
|
||
>Translation is considered a kind of modification, so you may
|
||
distribute translations of the Document under the terms of section
|
||
4. Replacing Invariant Sections with translations requires
|
||
special permission from their copyright holders, but you may
|
||
include translations of some or all Invariant Sections in addition
|
||
to the original versions of these Invariant Sections. You may
|
||
include a translation of this License provided that you also
|
||
include the original English version of this License. In case of
|
||
a disagreement between the translation and the original English
|
||
version of this License, the original English version will
|
||
prevail.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN512"
|
||
></A
|
||
>9. Termination</H1
|
||
><P
|
||
>You may not copy, modify, sublicense, or distribute the
|
||
Document except as expressly provided for under this License. Any
|
||
other attempt to copy, modify, sublicense or distribute the
|
||
Document is void, and will automatically terminate your rights
|
||
under this License. However, parties who have received copies, or
|
||
rights, from you under this License will not have their licenses
|
||
terminated so long as such parties remain in full
|
||
compliance.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN515"
|
||
></A
|
||
>10. Future Revisions of this License</H1
|
||
><P
|
||
>The Free Software Foundation may publish new, revised
|
||
versions of the GNU Free Documentation License from time to time.
|
||
Such new versions will be similar in spirit to the present
|
||
version, but may differ in detail to address new problems or
|
||
concerns. See <A
|
||
HREF="http://www.gnu.org/copyleft/"
|
||
TARGET="_top"
|
||
>http://www.gnu.org/copyleft/</A
|
||
>.</P
|
||
><P
|
||
>Each version of the License is given a distinguishing
|
||
version number. If the Document specifies that a particular
|
||
numbered version of this License "or any later version" applies to
|
||
it, you have the option of following the terms and conditions
|
||
either of that specified version or of any later version that has
|
||
been published (not as a draft) by the Free Software Foundation.
|
||
If the Document does not specify a version number of this License,
|
||
you may choose any version ever published (not as a draft) by the
|
||
Free Software Foundation.</P
|
||
></DIV
|
||
><DIV
|
||
CLASS="sect1"
|
||
><HR><H1
|
||
CLASS="sect1"
|
||
><A
|
||
NAME="AEN520"
|
||
></A
|
||
>How to use this License for your documents</H1
|
||
><P
|
||
>To use this License in a document you have written, include
|
||
a copy of the License in the document and put the following
|
||
copyright and license notices just after the title page:</P
|
||
><A
|
||
NAME="AEN523"
|
||
></A
|
||
><BLOCKQUOTE
|
||
CLASS="BLOCKQUOTE"
|
||
><P
|
||
> Copyright (c) YEAR YOUR NAME.
|
||
Permission is granted to copy, distribute and/or modify this document
|
||
under the terms of the GNU Free Documentation License, Version 1.1
|
||
or any later version published by the Free Software Foundation;
|
||
with the Invariant Sections being LIST THEIR TITLES, with the
|
||
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
|
||
A copy of the license is included in the section entitled "GNU
|
||
Free Documentation License".
|
||
</P
|
||
></BLOCKQUOTE
|
||
><P
|
||
>If you have no Invariant Sections, write "with no Invariant
|
||
Sections" instead of saying which ones are invariant. If you have
|
||
no Front-Cover Texts, write "no Front-Cover Texts" instead of
|
||
"Front-Cover Texts being LIST"; likewise for Back-Cover
|
||
Texts.</P
|
||
><P
|
||
>If your document contains nontrivial examples of program
|
||
code, we recommend releasing these examples in parallel under your
|
||
choice of free software license, such as the GNU General Public
|
||
License, to permit their use in free software.</P
|
||
></DIV
|
||
></DIV
|
||
></DIV
|
||
></BODY
|
||
></HTML
|
||
> |