diff options
Diffstat (limited to 'developer-doc/phb/cvs-examples.docbook')
| -rw-r--r-- | developer-doc/phb/cvs-examples.docbook | 692 |
1 files changed, 692 insertions, 0 deletions
diff --git a/developer-doc/phb/cvs-examples.docbook b/developer-doc/phb/cvs-examples.docbook new file mode 100644 index 0000000..ab34aee --- /dev/null +++ b/developer-doc/phb/cvs-examples.docbook @@ -0,0 +1,692 @@ +<appendix id="cvs-examples"> +<title>CVS examples</title> +<para> +It is not the intention of this document to give a complete introduction to +&cvs;. Nevertheless, a few examples should give a quick overview on the basic +operations to be performed by the developer. +</para> + +<para> +It is assumed, that the developer is registered with the &app; project and +has read/write access to the repository. Also, it is assumed, that the +necessary environment variables are setup, so that &cvs; knows how to access +the repository. Details about the settings can be found on the <ulink +url="http://www.sourceforge.net/">SourceForge.net</ulink> web-site. +</para> + +<para> +Throughout the next sections, the examples given use the &cvs; command line +interface. The options are abbreviated. The operations described here are also +accessible through various GUI clients available for &cvs;. Also, I usually +use the -q (quiet) option to suppress some messages issued by &cvs;. If you +omit the -q option, the output differs from the one shown here, even though +the result of the operation is the same. +</para> + +<section id="cvs-checkout"> +<title>Checking out from the repository</title> +<para> +The very first operation is to fill the sandbox. This is done using the +<command>checkout</command> operation. The first time the repository is +checked-out, it's location must be specified. This is done using the +<command>-d</command> option. In the example below, +you must replace <emphasis>username</emphasis> with your real username at +SourcForge.net. + +</para> + +<example> +<title>Filling the sandbox for the first time</title> +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -d &cvs-user;@&cvs-host;:&cvs-dir; co &cvs-module;</userinput> + + +</screen> +<para> +During the checkout process, &cvs; lists all filenames on the users screen +and stores information about the repository's +location and all the files checked out in the sandbox. Therefor, you do not +need to specify the repository location during following &cvs; operations +anymore. +</para> + +<para> +For the &app; project, a directory named <command>kmymoney2</command> is +created in your current working directory. +</para> +</example> + +<para> +The above example fills the sandbox with the HEAD revision of all files. +This stage is sometimes referred to as the <quote>latest-and-greatest</quote> +and is the latest development stage. +</para> + +<note> +<para> +If you plan to keep two or more branches of the project on your machine, +please see the chapter <emphasis> +<link linkend="multiple-branches">Keeping different +branches on the same machine</link></emphasis> for details. +</para> +</note> + +<para> +If for some reason, you need to checkout a version of the project that is +different from the development stage (e.g. you want to fix a bug in a +stable version), you can fill an empty sandbox by supplying the version-tag +as parameter to the checkout command. +</para> + +<example> +<title>Filling the sandbox for the first time with a specific version</title> +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -d &cvs-user;@&cvs-host;:&cvs-dir; co -r <emphasis>version-tag</emphasis> &cvs-module;</userinput> + + +</screen> +<para> +This will store the version labelled with the tag +<emphasis>version-tag</emphasis> in your sandbox. In case +<emphasis>version-tag</emphasis> is a branch-tag, you are able to modify +the files and check-in changes later on. In case, +<emphasis>version-tag</emphasis> is a standard tag, checkin operations will +be rejected by &cvs;. +</para> + +<para> +As in the previous example, the directory kmymoney2 is created as the +sandbox. +</para> +</example> +</section> + +<section id="cvs-checkin"> +<title>Checking in to the repository</title> +<para> +Once the sandbox is filled, changes to the project will be +applied by the developer. As soon as the developer is confident with the +changes, he is about to promote these changes to the other developers. He +does that by checking the changes back into the repository. +</para> + +<para> +Checking changes back into the repository should start by performing an +update procedure as described in <link linkend="cvs-update">the next +section</link>. This may seem strange, but updateing your sandbox will +transfer changes performed by other developers in the meantime to your +sandbox. It is good practice to re-compile the project if you notice that +updateing the sandbox changes it's contents. This assures that the project +is still compilable when you check-in your changes. +</para> + +<para> +The next step is to identify the changes you really want to promote. This +can be performed by the <command>diff</command> operation supported by +&cvs;. +</para> + +<example> +<title>Promote changes to the repository</title> +<para> +For the following example, I assume a single file that has been changed in +the sandbox (~/kmymoney2/kmymoney2/knewbankdlg.cpp) and that the current +directory is ~/kmymoney2/kmymoney2. Also, it is assumed, that the file +README has been updated by another person in the repository. Since the +README file has no influence on the compile process, we omit recompiling in +this example. +</para> + +<para> +The part of the original file that has been changed is shown here to +understand the output of the <userinput>cvs diff</userinput> +command shown below. The beginning of +the file is not included here as it is not changed. +</para> + +<programlisting role="C++"> + +void KNewBankDlg::okClicked() +{ + if (nameEdit->text().isEmpty()) { + KMessageBox::information(this, i18n("The institution name field is empty. Please enter the name."), i18n("Adding New Institution")); + nameEdit->setFocus(); + return; + } + + m_name = nameEdit->text(); + m_city = cityEdit->text(); + m_street = streetEdit->text(); + m_postcode = postcodeEdit->text(); + m_telephone = telephoneEdit->text(); + m_managerName = managerEdit->text(); + m_sortCode = sortCodeEdit->text(); + accept(); +} + + +</programlisting> + +<para> +The changed version of the method is included here. +</para> + +<screen> + +void KNewBankDlg::okClicked() +{ + if (nameEdit->text().isEmpty()) { + KMessageBox::information(this, i18n("The institution name field is empty. Please enter the name."), i18n("Adding New Institution")); + nameEdit->setFocus(); + + } else { + m_name = nameEdit->text(); + m_city = cityEdit->text(); + m_street = streetEdit->text(); + m_postcode = postcodeEdit->text(); + m_telephone = telephoneEdit->text(); + m_managerName = managerEdit->text(); + m_sortCode = sortCodeEdit->text(); + accept(); + } +} + + +</screen> + +<para> +Now as the file has been changed, the changes should be promoted to the +repository. As explained above, the process starts with checking for +changes made by other people. +</para> + +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -q upd</userinput> + U README + M knewbankdlg.cpp + <prompt>thb:~> </prompt> + + +</screen> + +<para> +The above shown output has the following meaning: +the file <command>README</command> is udpated (U) from the repository +to the sandbox because +it has been changed by someone else in the meantime. The contents of the file +in the sandbox will be replaced by the contents of the file in the +repository, because it has not been altered in the sandbox. +The file <command>knewbankdlg.cpp</command> has been modified (M) in the +sandbox and needs to be returned to the repository. +</para> + +<para> +<anchor id="cvs-source-changes"/> +As the next step, one should check what has been changed in the file +<command>knewbankdlg.cpp</command>. This is done using the following command: +</para> + +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -q diff knewbankdlg.cpp</userinput> + 74,75d73 + < return; + < } + 77,84c75,84 + < m_name = nameEdit->text(); + < m_city = cityEdit->text(); + < m_street = streetEdit->text(); + < m_postcode = postcodeEdit->text(); + < m_telephone = telephoneEdit->text(); + < m_managerName = managerEdit->text(); + < m_sortCode = sortCodeEdit->text(); + < accept(); + --- + > } else { + > m_name = nameEdit->text(); + > m_city = cityEdit->text(); + > m_street = streetEdit->text(); + > m_postcode = postcodeEdit->text(); + > m_telephone = telephoneEdit->text(); + > m_managerName = managerEdit->text(); + > m_sortCode = sortCodeEdit->text(); + > accept(); + > } + <prompt>thb:~> </prompt> + + +</screen> +</example> + +<para> +The output shows the changes between the current and the original revision +of the file. If this is what needs to be changed then the next step can be +started, which is checking the changes back into the repository. +</para> +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -q ci -m "Avoid return in the middle of a function" knewbankdlg.cpp</userinput> + Checking in knewbankdlg.cpp; + kmymoney2/kmymoney2/knewbankdlg.cpp,v <-- knewbankdlg.cpp + new revision: 1.10; previous revision: 1.9 + done + <prompt>thb:~> </prompt> + + +</screen> + + +<note> +<para> +If the option -m and the descriptive text is omitted on the command line, +&cvs; starts an editor where the developer has to enter a descriptive text +about the changes and save that file. Performing checkin operations that +way is meaningful, if the description is longer or covers more than one file. +</para> +</note> + +<para> +At this point, the changes are stored in the repository. An automatic mail +is generated and send to the kmymoney2-developer mailing list +<email>kmymoney2-developer@lists.sourceforge.net</email>. This mail +informs all other developers about your changes and is an indication for +them to <link linkend="cvs-update">update</link> their sandboxes. The +contents of the mail looks something like this: +</para> + +<screen> + + From: Thomas Baumgart <ipwizard@users.sourceforge.net> + To: kmymoney2-developer@lists.sourceforge.net + Date: Sat, 24 Nov 2001 12:23:00 -0800 + Subject: [Kmymoney2-developer] CVS update: + + Update of /cvsroot/kmymoney2/kmymoney2/kmymoney2 + In directory usw-pr-cvs1:/tmp/cvs-serv6662 + + Modified Files: + knewbankdlg.cpp + Log Message: + Avoid return in the middle of a function + _______________________________________________ + Kmymoney2-developer mailing list + Kmymoney2-developer@lists.sourceforge.net + https://lists.sourceforge.net/lists/listinfo/kmymoney2-developer + + + +</screen> + +<para> +While you checkin your changes, you should maintain the file +<command>kmymoney2/ChangeLog</command>. You could probably use the same +comments that you use for checkin in your changes or a more general note +for many changes. That depends on your changes. Once all your changes are +checked in, you also checkin <command>kmymoney2/ChangeLog</command>. +</para> +</section> + +<section id="cvs-update"> +<title>Updateing changes performed by other developers</title> +<para> +In case you noticed that other developers changed the repository - +fortunately you will be noticed by a mail to the developer mailing list if +that is the case - you should get those changes to your sandbox. This is +accomplished using the <command>update</command> command of &cvs;. +</para> + +<example> +<title>Updating the sandbox</title> +<para> +To update the local sandbox the following command is used. As most other +&cvs; commands, it operates recursively from the current working directory in +the sandbox. +</para> + +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -q upd</userinput> + U README + M knewbankdlg.cpp + <prompt>thb:~> </prompt> + + +</screen> + +<para> +The above shown output has the following meaning: +the file <command>README</command> is udpated (U) from the repository to +the sandbox because +it has been changed by someone else in the meantime. The contents of the +file +in the sandbox will be replaced by the contents of the file in the +repository, because it has not been altered in the sandbox. +The file <command>knewbankdlg.cpp</command> has been modified (M) in the +sandbox and needs to be returned to the repository. +</para> + +<para> +If you run the same command again, the output will change, as the file +<command>README</command> is now up-to-date. +</para> + +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -q upd</userinput> + M knewbankdlg.cpp + <prompt>thb:~> </prompt> + + +</screen> + + +</example> + +<para> +Sometimes it is useful to get an overview of what the status of certain +files in the repository is without modifying the sandbox (updating). This +can be accomplished by using the -n option to the update command. +</para> + +<example> +<title>Checking the status of files in the sandbox</title> +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -nq upd</userinput> + U README + M knewbankdlg.cpp + <prompt>thb:~> </prompt> + + +</screen> + +<para> +The status of the files is the same as explained above, but the file +<command>README</command> +will <emphasis>not</emphasis> be updated. It remains unchanged in the +sandbox. If you run this command again, the output remains. +</para> +</example> + +</section> + +<section id="dismissing-changes"> +<title>Dismissing changes</title> +<para> +It happens, that a developer tries to modify the source to gain a certain +functionality and then wants to discard the changes. This is no problem at +all with &cvs;. All the developer needs to do is to remove the file in the +sandbox and run the <command>update</command> command of &cvs;. This will +transfer the original version of the file in question to the sandbox. +</para> + +<para> +Let's assume, that the changes made to <command>knewbankdlg.cpp</command> +as outlined in <link linkend="cvs-source-changes">a previous chapter</link> should +be dismissed. The following commands perform this operation: +</para> + +<example> +<title>Reverting changes made to the sandbox</title> +<screen> + + <prompt>thb:~> </prompt><userinput>cvs -q upd</userinput> + M knewbankdlg.cpp + <prompt>thb:~> </prompt><userinput>rm knewbankdlg.cpp</userinput> + <prompt>thb:~> </prompt><userinput>cvs -q upd</userinput> + U knewbankdlg.cpp + <prompt>thb:~> </prompt><userinput>cvs -q upd</userinput> + <prompt>thb:~> </prompt> + + +</screen> +</example> + +</section> + +<section id="multiple-branches"> +<title>Keeping different branches on the same machine</title> +<para> +Whenever a configuration manager of the project decides to create a new +stable release, the developers face a problem: they are not allowed to add +new features to the software, only bug-fixes can be checked into the +repository. Until the configuration manager opens the sources for further +development, the developers are stuck. +</para> + +<para> +To avoid this dilemma, the configuration manager creates a branch off the +main development line when he creates the new stable release. Fixes will be +made to the release-branch, new developments will be made to the main +branch. This eliminates two problems: the configuration manager does not +have to lock the current stage and the developers can continue with the +implementation of features planned for the next release. Nevertheless, the +stable version can be changed (fixes can be applied) and those fixes can be +transferred to the main development branch so that they do not show up in +future releases of the software. +</para> + +<para> +Since in our project the developers will work on both, bug fixes and new +development at the same time, it is convenient to have two sandboxes on the +development machine. For the following examples, I have two subdirectories +in my $HOME for the project. One is for the release and the other for the +develepment branch. I name them <command>stable</command> for the release +branch and +<command>devel</command> for the development branch. +</para> + +<para><command>The development branch</command></para> +<para> +The development branch is the same as you use it today. Just move it from +it's current location to $HOME/devel. I kept it directly in my $HOME +directory so I did it as follows: + +<example> +<title>Keeping stable and development branch on one machine</title> +<screen> + + <prompt>thb:~> </prompt><userinput>md devel</userinput> + <prompt>thb:~> </prompt><userinput>md stable</userinput> + <prompt>thb:~> </prompt><userinput>mv kmymoney2 devel</userinput> + <prompt>thb:~> </prompt> + + +</screen> +</example> +Now the development sources are found in ~/devel/kmymoney2/. It is +important to move all the CVS directories as well. If you start from +scratch, then you just follow the instructions on how to checkout the +project and do that in the <command>devel</command> subdirectory. See the +chapter <emphasis> +<link linkend="cvs-checkout">Checking out from the repository</link> +</emphasis> for an example. +</para> + +<para><command>The release branch</command></para> +<para> +As soon as a release branch has been created by the configuration manager, +you should get it to the stable directory. You do this by checking it out +with the tag that has been assigned. The conventions have been defined in +the chapter about <link linkend="version-mgmt">Version management</link>. +For this example, I assume that a release branch for version 0.4 exists in +the repository. + +<footnote> +<para>Guess when I wrote this chapter ;-)</para> +</footnote> +</para> + +<example> +<title>Checking out the stable branch for the first time</title> +<screen> + + <prompt>thb:~> </prompt><userinput>cd stable</userinput> + <prompt>thb:~/stable> </prompt><userinput>cvs -d &cvs-user;@&cvs-host;:&cvs-dir; \ <footnote> +<para> +The back-slash is inserted here to break the line for readability. For real usage, the command has to be entered on a single line. +</para> +</footnote> + co -r <emphasis>rel-0-4-branch</emphasis> &cvs-module;</userinput> + <prompt>thb:~/stable> </prompt> + + +</screen> +</example> + +<para> +At this point it is important to use the <emphasis>branch-tag</emphasis> to +be able to modifiy the files and check them back into the repository. If +you are in the subdirectory containing the release-branch and you perform a +<command>cvs update</command>, you will only get those changes, that were +made on the branch. Also, changes are checked back into the release branch +and do <emphasis>NOT</emphasis> show up on the development branch. +</para> + +<note> +<para> +If you want to keep more than one stable branch on your development +machine, you can add the version number to the stable directory (e.g. +stable-0.4, etc.) +</para> +</note> +</section> + +<section id="promoting-changes"> +<title>Promoting bug-fixes to the main branch</title> +<para> +Usually, changes made to the release-branch fix a problem. In many cases the +problem still exists in the development branch. Therefor, it is +necessary to promote the changes made on the release branch back to the +development branch. +</para> + +<para> +In most cases, it is very easy to promote the changes. The developer must +be very careful though, as the fix might not be applicable in it's form to +the development branch anymore as things might have changed drastically due +to new features. +<footnote> +<para> +This is one of the reasons, why I suggest to apply the fix to the release +branch and promote it to the developer branch, as the fix as it works on +the release branch might +break things and broken software is definitly something we do not want + to happen on the stable branch. +</para> +</footnote> +</para> + +<para> +In this example, I assume changes were made to the single file README. +<footnote> +<para> +Fortunately, the error found was a documentation problem ;-) +</para> +</footnote> + +A complex fix +could cover many files. The procedure described in the following is then +required for each of them seperately. Further on, I assume that the change +has been checked in and that the revision was 1.14.2.1 before the fix and +is now 1.14.2.2. +</para> + +<example> +<title>Promoting a change from the release to the development branch</title> +<screen> + + <prompt>thb:~> </prompt><userinput>cd devel/kmymoney2</userinput> + <prompt>thb:~/devel/kmymoney2> </prompt><userinput>cvs -q upd -j 1.14.2.1 -j 1.14.2.2 README</userinput> + <prompt>thb:~/devel/kmymoney2> </prompt><userinput>vi README</userinput> + <prompt>thb:~/devel/kmymoney2> </prompt><userinput>cvs ci -m "Included fix #493920" README</userinput> + <prompt>thb:~/devel/kmymoney2> </prompt> + + +</screen> +</example> + +<para> +First, I go into the devel directory. Then I promote the changes to the +README file in the development branch from the repository, verify the +changes made (and possibly correct them) and checkin the changes to the +development branch. That's it! +<footnote> +<para> + Of course, a fix to a source code file would +be followed by a visual inspection (that's where <command>vi</command> or +<command>kdevelop</command> come into play) and a compile run with further +testing before the change is checked back into the repository. +</para> +</footnote> + +</para> + +<note> +<para> +It's important to perform this procedure for every file affected by the fix +seperatly, as the revision numbers usually differ significantly between +the files. Also, I suggest to fix each problem seperately. This reduces +further problems while promoting the changes back to the development +branch (e.g. one can leave out a fix completely if it does not apply at all +to the development branch). +</para> +<para> +If the fix is very simple, it can certainly be promoted manually to the +development directory tree by merely re-typing it. +</para> +</note> +</section> + +<section id="create-stable-example"> +<title>Creating a new stable release</title> +<para> +The procedure that needs to be followed is defined in a <link +linkend="create-stable-procedure">previous chapter</link>. +On the first glimpse, it seems rather complecated but it is not. +</para> + +<para> +If you follow the procedure as it has been defined, you will understand the +commands in our example. I assume to have a current unstable version of +0.3.x which will result in the stable version 0.4 and the next development +version of 0.5.x. Further on, I assume, that I already differentiate +between development and release directories. Also, the version number +maintained with KDevelop is setup correctly (0.4.pre1) and all files are +checked into the repository. +</para> + +<example> +<title>Creating a new stable branch</title> + +<screen> + + <prompt>thb:~> </prompt><userinput>cd devel/kmymoney2</userinput> + <prompt>thb:~/devel/kmymoney2> </prompt><userinput>cvs tag rel-0-4-pre1</userinput> + <prompt>thb:~/devel/kmymoney2> </prompt><userinput>cvs tag -b rel-0-4-branch</userinput> + + Now modify the version number in KDevelop to 0.5.0, regenerate the files and + checkin the changes as usual. + + <prompt>thb:~/devel/kmymoney2> </prompt><userinput>cvs tag rel-0-5-base</userinput> + <prompt>thb:~/devel/kmymoney2> </prompt> + + +</screen> +</example> + +<tip> +<para> +Because I know, that I will need the branch sooner or later to fix some +problems, I continue to check it out into the stable directory. See <link +linkend="multiple-branches">Keeping different branches on the same +machine</link> for details. +</para> +</tip> + +</section> +</appendix> + |