LDP
/
LDP
mirror of https://github.com/tLDP/LDP
0
1
Fork 0
Code Releases Activity

updated

This commit is contained in:
gferg 2001-11-29 15:26:55 +00:00
parent d368505358
commit 4d84040a04
1 changed files with 250 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

311
LDP/ref/docbook/CVS-BestPractices/CVS-BestPractices.sgml
View File

@ -1,7 +1,7 @@
<!DOCTYPE ARTICLE PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!-- Document version -->
<!ENTITY DOCVERSION "0.1">
<!ENTITY DOCVERSION "0.2">
<!-- File Includes -->
<!ENTITY GFDL-FILE SYSTEM "gfdl.sgml">
@ -12,7 +12,7 @@
<!ENTITY CVSAB "CVS">
<!ENTITY SCMAB "SCM">
<!ENTITY SCM "Software configuration management">
<!ENTITY MYEMAIL "vivekv@users.sourceforge.net">
<!ENTITY MYEMAIL "vivekv at users.sourceforge.net">
]>
@ -25,10 +25,16 @@
<firstname>Vivek</firstname>
<surname>Venugopalan</surname>
<affiliation>
<address><email>vivekv@users.sourceforge.net</email></address></affiliation>
<address><email>vivekv at users.sourceforge.net</email></address></affiliation>
</author>
<revhistory>
<revision>
<revnumber>0.2</revnumber>
<date>2001-11-27</date>
<authorinitials>vv</authorinitials>
<revremark>Incorporated first round of feedback and some minor fixes</revremark></revision>
<revision>
<revnumber>0.1</revnumber>
<date>2001-11-20</date>
@ -53,8 +59,9 @@ projects.
<title>Introduction</title>
<blockquote>
<attribution>unknown</attribution>
<literallayout>A tool is only as good as you use it
<attribution>Henry David Thoreau (1817-1862)
</attribution>
<literallayout>Men have become the tools of their tools.
</literallayout>
</blockquote>
@ -72,7 +79,7 @@ a viable alternative to other commercial &SCM; tools. </para>
practices for deploying &CVSAB; as the backbone &SCMAB; tool for large
software development projects. Having answered this question many times
verbally as a bunch of <quote>gotchas</quote> on &CVSAB;, it was time to put
down on paper some of the best practices that I have adopted while managing
down on paper some of the best practices that will work well for
&CVSAB; based projects. </para>
<!-- Section2: copyright -->
@ -80,17 +87,16 @@ down on paper some of the best practices that I have adopted while managing
<sect2 id="copyright">
<title>Copyright Information</title>
<para> This document is Copyright &copy; 2001 Vivek Venugopalan.
Permission is granted to copy, distribute and/or modify this document
under the terms of the <link linkend="gfdl"><citetitle>GNU Free
Documentation License</citetitle></link>, 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 <xref linkend="gfdl">.
</para>
<para> This document is Copyright &copy; 2001 Vivek Venugopalan. Permission
is granted to copy, distribute and/or modify this document under the terms of
the <link linkend="gfdl"><citetitle>GNU Free Documentation
License</citetitle></link>, 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 <xref
linkend="gfdl">. </para>
<para> 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
<para> 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.
</para>
@ -99,16 +105,13 @@ however, the author would like to be notified of any such distributions.
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. </para>
under certain conditions; please contact the author at the address given
below. </para>
<para> 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. </para>
<para> If you have any questions, please contact
<email>linux-howto@metalab.unc.edu</email> </para> </sect2>
document, and would like to be notified of any plans to redistribute the same.
</para>
<!-- Section2: disclaimer -->
@ -121,9 +124,9 @@ course be damaging to your system. Proceed with caution, and although this is
highly unlikely, the author(s) do not take any responsibility for that.
</para>
<para> 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. </para>
<para> 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. </para>
<para> Naming of particular products or brands should not be seen as
endorsements. </para>
@ -136,17 +139,42 @@ major installation and backups at regular intervals. </para> </sect2>
<sect2 id="newversions">
<title>New Versions</title>
<indexterm> <primary></primary> </indexterm>
<para> The version number of this document is &DOCVERSION;. </para>
<para> The latest version of this document can be obtained from <ulink
url="http://www.linuxdoc.org">The linux documentation project</ulink> </para>
<para> The latest version of this document can be obtained from </para>
<orderedlist>
<listitem>
<para>
<ulink url="http://www.geocities.com/vivekv/cvs-bestpractices/index-cvs-bestpractices.html">My website</ulink>
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.linuxdoc.org/doc.html">The linux documentation project</ulink>
</para>
</listitem>
</orderedlist>
</sect2>
<!-- Section2: credits -->
<!-- Nothing yet. Will do so after the first release and the feedback. -->
<sect2 id="credits">
<title>Credits</title>
<para>The list of people who have provided inputs and information for this
paper in no particular order are.
<orderedlist>
<listitem>
<para>Jens-Uwe Mager
</para>
</listitem>
<listitem>
<para>Jorgen Grahn
</para>
</listitem>
</orderedlist>
</para>
</sect2>
<!-- Section2: feedback -->
<sect2 id="feedback">
@ -181,6 +209,10 @@ additions, comments and criticisms to the following email address :
</para>
<itemizedlist>
<listitem>
<para>Keep System clocks in Sync
</para>
</listitem>
<listitem>
<para>Do not share the sandbox
</para>
</listitem>
@ -193,12 +225,35 @@ additions, comments and criticisms to the following email address :
</para>
</listitem>
<listitem>
<para>Cleanup after completion
</para>
</listitem>
<listitem>
<para>Check-in often
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Server Configuration
</para>
<itemizedlist>
<listitem>
<para>&CVSAB; Server side scripting
</para>
</listitem>
<listitem>
<para>&CVSAB; Server notification
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Branching and Merging
</para>
@ -258,7 +313,7 @@ additions, comments and criticisms to the following email address :
</listitem>
<listitem>
<para>Institutionalizing and Process
<para>Institutionalize in the Organization
</para>
<itemizedlist>
<listitem>
@ -281,79 +336,174 @@ additions, comments and criticisms to the following email address :
<!-- Using GUI Tools -->
<sect1 id="section1-guitools">
<title>Using GUI Tools</title>
<title>Using <acronym>GUI</acronym> Tools</title>
<para> Developers typically use integrated development environments that have
<para>The traditional interface available for CVS is the command-line client.
There has also been a slew of GUI client applications that can
<quote>talk</quote> to a &CVSAB; server. These GUI clients provide a
<quote>point and click</quote> interface to the &CVSAB; repository. This
paper recommends using such GUI clients during the initial deployment of
&CVSAB; in an organization.</para>
<para>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 &CVSAB; usage and instead allow them to be
productive from day one. Developers who are accustomed to other CM tools will
find the &CVSAB; command-line interface daunting. The adoption and usage of
&CVSAB; can be improved by using GUI tools for &CVSAB; clients. GUI tools for
&CVSAB; are available at <ulink url="www.cvsgui.org">www.cvsgui.org</ulink>.
GUI interfaces are available for most of the popular platforms (Windows, Mac
and Linux). In addition, on the Windows platform there is a SCC extension
that allows integration of &CVSAB; as the configuration control tool with
popular IDE.</para>
&CVSAB; can be improved by using GUI tools for &CVSAB; clients. </para>
<para> GUI tools for &CVSAB; are available at <ulink
url="www.cvsgui.org">www.cvsgui.org</ulink>. GUI interfaces are available for
most of the popular platforms (Windows, Mac and Linux). In addition, on the
Windows platform there is an <acronym>SCC</acronym> extension that allows
integration of &CVSAB; as the configuration control tool with popular
IDE.</para>
</sect1>
<!-- Developer Sandbox -->
<sect1 id="section1-devsandbox">
<title>Developer Sandbox</title>
<para>The developer <quote>sandbox</quote> is where each developer keeps his
or her working copy of the code base. 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 &CVSAB; repository. In addition, changes
made in the repository by others have to be updated in the sandbox on a
regular basis. </para>
or her working copy of the code base. In &CVSAB; 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 &CVSAB; repository. In addition, changes made in the repository by
others have to be updated in the sandbox on a regular basis. </para>
<para>The best practices related to developers sandbox are:
</para>
<sect2 id="section2-clockinsync">
<title>Keep System clocks in Sync</title>
<para>&CVSAB; 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 &CVSAB; getting confused. Thus system clocks must be
kept in sync by use of a central time server or similar mechanism.
</para>
<note>
<para>Can CVS handle clients situated in different timezone? This is an area
that is not very familiar to me. I would like to hear some thoughts on the
same.</para>
</note>
</sect2>
<sect2 id="section2-dontshare">
<title>Do not share the sandbox</title>
<para>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
workspaces are shared, then the developers themselves will not be aware of the
sandboxes are shared, then the developers themselves will not be aware of the
changes made to the files resulting in confusion. </para>
<para>In &CVSAB;, the sandbox is created automatically when a working copy is
checked out for a &CVSAB; project using the <command>cvs checkout
{project-name}</command> command. </para>
<para>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. </para>
<para>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.</para>
</sect2>
<sect2 id="section2-workinside">
<title>Do not work outside the sandbox</title>
<para>The sandbox can be thought of as a controlled area within which &CVSAB;
can track for changes made to the various source files. Files belonging to
other developers will be automatically updated by &CVSAB;. Thus the developer
who lives within the sandbox will stand to gain a lot of benefits of
concurrent development. This benefit cannot be achieved for work done outside
a sandbox. </para>
<para>The sandbox can be thought of as a controlled area within which
&CVSAB; can track for changes made to the various source files. Files
belonging to other developers can be automatically updated by &CVSAB;. Thus
the developer who lives within the sandbox will stand to gain a lot of
benefits of concurrent development that cannot be done if work is done
outside a sandbox. </para> </sect2>
</sect2>
<sect2 id="section2-syncup">
<title>Stay in Sync with the repository</title>
<para>To gain the benefits of working within a sandbox as mentioned above,
the developer must keep his or her workspace in sync with the main
the developer must keep his or her sandbox in sync with the main
repository. A regular <command>cvs update</command> with the appropriate
tag will ensure that the sandboxes are kept up to date. </para> </sect2>
tag or branch name will ensure that the sandboxes are kept up to date. </para> </sect2>
<sect2 id="section2-cleanupatcompletion">
<title>Cleanup after completion</title>
<para>Make sure that the sandbox is cleaned up after completion of the change.
This can be done in &CVSAB; by using the <command>cvs release</command>
command. This ensures that no old version of the code 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.
</para>
</sect2>
<sect2 id="section2-checkin">
<title>Check-in Often</title>
<para>To help other developers keep their code in sync with your code, you
must check-in your code often into the &CVSAB; repository. As soon as a
piece of code is completed and tested, check-in the changes using a
<command>cvs commit</command> to ensure that your changes are committed to
the &CVSAB; repository. </para>
must check-in your code often into the &CVSAB; repository. The best practice
would be to check-in soon as a piece of code is completed, reviewed and
tested, check-in the changes using a <command>cvs commit</command> to ensure
that your changes are committed to the &CVSAB; repository.
</para>
<para> &CVSAB; promotes concurrent development. Concurrent development is
possible only if all the other developers are aware of the ongoing changes on
a regular basis. </para>
<note>
<para>One of the <quote>bad</quote> practices that commonly occur is sharing
of source code files between developers by email. This works against most of
the best practices mentioned above. To share source code updates between two
developers, &CVSAB; must be used as the communication medium. This will
ensure that &CVSAB; is <quote>aware</quote> of the code change and can track
them. Thus, audit trail can be established if necessary. </para>
</note>
</sect2>
</sect1>
<sect1 id="section1-serverconfig">
<title>Server Configuration</title>
<para>This section deals with best practices for &CVSAB; server side setup and
configuration.
</para>
<sect2 id="section2-scripting">
<title>Server side scripting</title>
<para>Server side scripting refers to the ability to make &CVSAB; server
execute certain scripts when an event occurs. I am currently not aware of any
best practices in this area. Suggestions are welcome.
</para>
</sect2>
<sect2 id="section2-notification">
<title>Server Notification</title>
<para>The &CVSAB; server can be configured to notify through e-mails in the
event of a commit happening. This can be used to verify if code commits are
occurring during the course of a release build. If such commits occur, based
on the project policy, such commits can be ignored or the entire build
automatically restarted.</para>
</sect2>
</sect1>
@ -378,6 +528,20 @@ applies those differences to the project at the tip of the trunk. </para>
owner assigned who will be responsible for. </para>
<orderedlist>
<listitem>
<para>Keep the list of configurable items for the branch or trunk.
</para>
<para>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.
</para>
</listitem>
<listitem>
<para>Establish a working policy for the branch or trunk.
</para>
@ -485,7 +649,7 @@ release tagging practice (see <xref linkend="section2-tagrelease">). </para>
<sect1 id="section1-chgpropagation">
<title>Change Propagation</title>
<para>Change propagation practices explores how changes made to one version of
<para>Change propagation practices explore how changes made to one version of
the application are migrated to other living versions of the application.
</para>
@ -504,6 +668,20 @@ 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. </para>
<para>In the case of changes occuring on branches for a long period of time,
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.
</para>
<para>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 <quote>moved</quote> after each intermediate merge
by using the <command>-F</command> option. This eliminates duplicate merging
issues during intermediate merges.
</para>
</sect2>
</sect1>
@ -548,6 +726,9 @@ 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. </para>
<para>By automating the build process, the task of building often becomes
less burdensome. </para>
</sect2>
<sect2 id="section2-ensurecheckin">
@ -568,6 +749,10 @@ will surface during the build process itself (makefiles etc.,) or during the
regression testing of the product (older version of the file checked in).
</para>
<para>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. </para>
</sect2>
</sect1>
@ -593,6 +778,9 @@ the organization, tools such as &CVSAB; will be looked at as aiding
this process instead of acting as a general development overhead.
</para>
<para>Change management is quite a vast topic that cannot be done justice
here. Please look up some websites on change management. </para>
</sect2>
<sect2 id="section2-objectives">
@ -635,3 +823,4 @@ evolving document. Please send your comments and ideas to
&GFDL-FILE;
</article>