3
3
<title>Moodle Docs: How to use CVS</title>
4
<link rel="stylesheet" href="docstyles.css" type="TEXT/CSS">
5
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
4
<link rel="stylesheet" href="docstyles.css" type="TEXT/CSS">
5
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6
<style type="text/css">
8
.style1 {color: #990000}
9
.style3 {color: #990000; font-weight: bold; }
7
17
<body bgcolor="#ffffff">
8
<h1>Using CVS to access and update Moodle source code</h1>
10
<p>CVS is the Concurrent Versioning System. It's a commonly used way of storing
11
source code because it keeps versions of all files so that nothing is ever
12
lost, and usage by different people is tracked. It also provides ways to merge
13
code if two or more people are working on the same file. All code and all
14
versions are stored on a central server (in the case of Moodle, at <a target="_top" href="http://www.sf.net/">Sourceforge</a>).
16
<p>If you just want to access the current CVS version of Moodle with read-only access then
17
you don't need this page - just follow the simpler CVS instructions on the <a target="_top" href="http://moodle.org/download">Moodle download page</a>.</p>
19
<p>To use <a target="_top" href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/moodle/moodle/">Moodle's
20
CVS archive</a> (as a <a target="_top" href="http://sourceforge.net/project/memberlist.php?group_id=30935">developer
21
with write access</a>), you first need to have an <a href="http://sourceforge.net/account/register.php">account
22
on Sourceforge</a>. For the examples on this page, let's assume your username
23
is <strong><font color="#990000">myusername</font></strong> and your password
24
is <strong><font color="#990000">mypassword</font></strong>. Take special note of the
25
sourceforge instructions to <a target="_top" href="http://sourceforge.net/docman/display_doc.php?docid=768&group_id=1#develhomedir">create your CVS home directory</a> - something you have to
26
do with every new account to "enable" it for CVS. Basically you just have to use ssh to interactively connect to cvs.sourceforge.net.</p>
29
a working Sourceforge account, contact <a
30
target="_top" href="http://moodle.org/user/view.php?id=1&course=1">Martin Dougiamas</a> so he can give you write access
31
to particular Moodle directories.</p>
33
<p>To avoid being prompted for <strong><font color="#990000">mypassword</font></strong>
34
every time you run a CVS command, follow the <a target="_top" href="http://sourceforge.net/account/editsshkeys.php">Sourceforge
35
directions for using authorized keys</a>. This step is optional, but it can
36
make your CVS experience a lot nicer.</p>
37
<p>With that done, you should have all the permissions you need, so you just
38
need to set up your machine and download the current sources so you can start
39
working on them. Below are instructions for Unix and Windows systems.</p>
40
<h2>1. Using CVS on Unix</h2>
42
<p>Sourceforge CVS uses ssh as a transport layer for security, so you will
43
have to set this CVS_RSH environment variable in your Unix shell:</p>
45
<pre><strong>setenv CVS_RSH ssh</strong> (for csh, tcsh etc)</pre>
46
<pre><strong>export CVS_RSH=ssh</strong> (for sh, bash etc)</pre>
48
<p>It's best to put this in your .bashrc or .cshrc so you don't have to type
49
it all the time. Then, check out Moodle using this (all one line): </p>
51
<pre><strong>cvs -z3 -d:ext:myusername@cvs.sourceforge.net:/cvsroot/moodle co moodle</strong></pre>
53
<p>The command is similar for other CVS modules (such as the contrib folder or the MySQL Admin folder):</p>
55
<pre><strong>cvs -z3 -d:ext:myusername@cvs.sourceforge.net:/cvsroot/moodle co contrib</strong><br />
56
<strong>cvs -z3 -d:ext:myusername@cvs.sourceforge.net:/cvsroot/moodle co mysql</strong></pre>
58
<p>Don't try to do run this first CVS command over an existing moodle installation
59
- start fresh with a new directory.</p>
60
<p>Note that you will be prompted for <strong><font color="#990000">mypassword</font></strong>
61
for each command unless you set up <a target="_top" href="http://sourceforge.net/account/editsshkeys.php">authorized
63
<p>Now, you should have a new 'moodle' directory. You can rename it and move
64
it around if you like. Go into it: </p>
66
<pre><strong>cd moodle </strong></pre>
68
<p>All the latest Moodle files should be in there. You can now change files
69
in your copy. To compare your files against the main CVS copy on the server
70
use cvs diff, eg: </p>
72
<pre><strong>cvs diff -c config-dist.php
73
cvs diff -c lang</strong></pre>
75
<p>To fetch the latest updates from the server use: </p>
77
<pre><strong>cvs update -dP</strong> </pre>
79
<p>To copy your new files back to the server you would do something like:
18
<h1>CVS for Moodle Developers</h1>
20
<p>CVS is the <strong>Concurrent Versioning System</strong>, a commonly-used way of managing source code for large software projects. CVS keeps all versions of all files so that nothing is ever lost, and usage by different people is tracked. It also provides ways to merge code if two or more people are working on the same file. All code and all versions are stored on a central server (in the case of Moodle, at <a target="_top" href="http://www.sf.net/">Sourceforge</a>). </p>
21
<p>If you just want to download Moodle using CVS to run a site, then you probably don't need this page - just follow the simpler CVS instructions on the <a target="_top" href="http://moodle.org/download">Moodle download page</a>.</p>
24
<li><a href="#1">Joining the project as a developer</a></li>
25
<li><a href="#2">CVS Modules</a> </li>
26
<li><a href="#3">Basic CVS Commands</a> <br />
27
3.1. <a href="#3.1">CVS on Unix</a> <br />
28
3.2. <a href="#3.2">CVS on Windows</a></li>
29
<li> <a href="#4">Working with Branches</a><br />
30
4.1. <a href="#4.1">Trunk development</a><br />
31
4.2. <a href="#4.2">Stable branches for each release</a><br />
32
4.3. <a href="#4.3">Feature branches for large changes</a> </li>
35
<h2><a name="1"></a>1. Joining the project as a developer</h2>
37
<p>So, you've been offered CVS write access to help us develop and maintain Moodle! <a href="http://sourceforge.net/project/memberlist.php?group_id=30935">Welcome aboard</a>!</p>
38
<p>To be able to write changes into <a target="_top" href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/moodle/moodle/">Moodle's CVS archive</a>, you first need to have an account at Sourceforge (<a href="http://sourceforge.net/account/register.php">registration is free and easy</a>). For the examples on this page, let's assume your username is <strong><font color="#990000">myusername</font></strong> and your password is <strong><font color="#990000">mypassword</font></strong>. Take special note of the sourceforge instructions to <a target="_top" href="http://sourceforge.net/docman/display_doc.php?docid=768&group_id=1#develhomedir">create your CVS home directory</a> - something you have to do with every new account to "enable" it for CVS. Basically you just have to use ssh to interactively connect to cvs.sourceforge.net.</p>
39
<p>Once you have a working Sourceforge account, contact <a
40
target="_top" href="http://moodle.org/user/view.php?id=1&course=1">Martin Dougiamas</a> so he can set up your account with write access to particular Moodle directories.</p>
41
<p>To avoid being prompted for <strong><font color="#990000">mypassword</font></strong> every time you run a CVS command, follow the <a target="_top" href="http://sourceforge.net/account/editsshkeys.php">Sourceforge directions for using authorized keys</a>. This step is optional, but it can make your CVS experience a lot nicer.</p>
42
<p>With that done, you should have all the permissions you need, so you just need to set up your machine and download the current sources so you can start working on them. </p>
45
<h2><a name="2" id="2"></a>2. CVS Modules</h2>
47
<p>Within CVS, the word "modules" refers to separate collections of code. In Moodle we have the following modules within our repository:</p>
49
<p><strong>moodle</strong> - the main Moodle source code</p>
50
<p><strong>contrib</strong> - user contributions and other assorted code in development</p>
51
<p><strong>mysql</strong> - a customised phpMyAdmin to plug into Moodle for database admin</p>
52
<p><strong>windows-cron</strong> - a small package that makes cron possible on Windows systems</p>
53
<p><strong>docs</strong> - various extra user-contributed documentation</p>
55
<p>Most people are working on the existing features in the <strong>moodle</strong> module, but many are also contributing new ideas in the <strong>contrib</strong> modules. Once code reaches a certain level of maturity in the <strong>contrib</strong> area, it can be migrated over into the main <strong>moodle</strong> tree. </p>
58
<h2><a name="3" id="3"></a>3. Basic CVS Commands </h2>
60
<h3><a name="3.1" id="3.1"></a>3.1 CVS on Unix </h3>
62
<p>Sourceforge CVS uses ssh as a transport layer for security, so you will have to set a CVS_RSH environment variable in your Unix shell. It's best to put these commands in your .bashrc or .cshrc so you don't have to type it all the time<strong>:</strong></p>
63
<div class="commandline">setenv CVS_RSH ssh <em>(for csh, tcsh etc)</em><br />
64
export CVS_RSH=ssh <em>(for sh, bash etc)</em></div>
65
<p>Next, you can check out the latest development version of Moodle using this (all one line): </p>
66
<div class="commandline">cvs -z3 -d:ext:<span class="style1">myusername</span>@cvs.sourceforge.net:/cvsroot/moodle co moodle</div>
67
<p>The command is similar for other CVS modules:</p>
68
<div class="commandline">cvs -z3 -d:ext:myusername@cvs.sourceforge.net:/cvsroot/moodle co contrib</div>
69
<p>Don't try to do run this first CVS command over an existing moodle installation: start fresh with a new directory.</p>
70
<p>Note that you will be prompted for <strong><font color="#990000">mypassword</font></strong> for each command unless you set up <a target="_top" href="http://sourceforge.net/account/editsshkeys.php">authorized keys</a>.</p>
71
<p>Now, you should have a new 'moodle' directory. You can rename it and move it around if you like. Go into it: </p>
72
<div class="commandline">cd moodle </div>
73
<p>All the latest Moodle files should be in there. You can now change files in your copy. To compare your files and directories against the main CVS copy on the server use cvs diff, e.g.: </p>
74
<div class="commandline">cvs diff -c config-dist.php<br />
75
cvs diff -c lang </div>
76
<p>To fetch the latest updates from the server use: </p>
77
<div class="commandline">cvs update -dP</div>
78
<p>To copy your new files back to the server you would do something like: </p>
79
<div class="commandline">cd lang/ca <br />
81
<p>You will be prompted to add some comments (depends on your default text editor) ... add a meaningful comment and close the editor ... the files will be sent to Sourceforge and stored. Done! </p>
82
<p>To save more time you can put default arguments into a file called .cvsrc in your home directory. For example, mine contains: </p>
83
<div class="commandline">diff -c <br />
85
<p>Try 'cvs help' for more details ... </p>
88
<h3><a name="3.2" id="3.2"></a>3.2 CVS on Windows </h3>
90
<p>First, you need to download a completely fresh copy of Moodle using your developer account.</p>
95
<li> Get TortoiseCVS from <a target="_top" href="http://www.tortoisecvs.org/">tortoisecvs.org</a> and install it, then reboot.</li>
96
<li>Find or create a new folder somewhere where you want Moodle to be downloaded to.</li>
97
<li>Right-mouse-click that folder and choose "<strong>CVS Checkout</strong>" from the menu. You should see a dialog box.</li>
98
<li>Copy this text into the CVSROOT field (using your own username!):
99
<pre> :ext:<font color="#990000">myusername</font>@cvs.sourceforge.net:/cvsroot/moodle</pre>
101
<li>Under the "Module" field, type "<strong>moodle</strong>" to get the latest development version of Moodle, "<strong>contrib</strong>" to get the contributions directory, or "<strong>mysql</strong>" to get the MySQL Admin module.</li>
102
<li>Press the button: "<strong>OK</strong>" and everything should be downloaded.<br />
108
<p>A dialog box should show all the files being downloaded, and after a while you should have a complete copy of Moodle. After this first checkout, you can fetch the latest updated files from the CVS server:</p>
113
<li> Right-mouse-click on your Moodle folder (or any file) and select "<strong>CVS Update</strong>". </li>
114
<li>Sit back and watch the logs scroll by. Take note of conflicts that may occur if your local code has changes that conflict with the incoming versions - you will need to edit these files and resolve the conflicts manually. <br />
120
<p>After modifying files (you will notice their icons change from green to red!), you can commit them back to the CVS server like this:</p>
125
<li> Right-mouse-click on your Moodle folder (or any file) and select "<strong>CVS Commit...</strong>".</li>
126
<li>In the dialog box, type a clear description of the changes you are committing.</li>
127
<li>Click "OK". Your changes will be sent to the server.<br />
134
<h2><a name="4" id="4"></a>4. Working with Branches</h2>
136
<p>This diagram shows how the main <strong>moodle</strong> module branches into different versions over time.</p>
137
<p align="center"><img src="pix/cvstree.png" width="500" height="200"></p>
138
<p align="left">To see all the current tags and branches that are available, use this command on any old file (such as index.php in the top moodle directory):</p>
139
<div class="commandline">cvs status -v index.php</div>
140
<p>Some tagging guidelines:</p>
142
<li>Tag and branch names should always be all upper-case.</li>
143
<li>Tags and branches should ALWAYS be applied to the <strong>entire module</strong> (all of Moodle). Don't tag individual files or directories. </li>
144
<li>We don't allow renaming of tags because people may be relying on them, so get them right the first time! </li>
82
<pre><strong>cd lang/ca
83
cvs commit</strong> </pre>
85
<p>You will be prompted to add some comments (depends on your default text
86
editor) ... add a meangingful comment and close the editor ... the files
87
will be sent to Sourceforge and stored. Done! </p>
88
<p>To save more time you can put default arguments into a file called .cvsrc
89
in your home directory. For example, mine contains: </p>
92
update -dP</strong> </pre>
94
<p>Try 'cvs help' for more details ... </p>
97
<h2>2. Using CVS on Windows</h2>
99
<p>First, you need to download a completely fresh copy of Moodle using your
100
developer account.</p>
102
<p> 1. Get TortoiseCVS from <a target="_top" href="http://www.tortoisecvs.org/">tortoisecvs.org</a>
103
and install it, then reboot.<br>
105
2. Find or create a new folder somewhere where you want Moodle to be downloaded
108
3. Right-mouse-click that folder and choose "<strong>CVS Checkout</strong>"
109
from the menu. You should see a dialog box.<br>
111
4. Copy this text into the CVSROOT field (using your own username!):</p>
113
<pre> :ext:<font color="#990000">myusername</font>@cvs.sourceforge.net:/cvsroot/moodle</pre>
116
5. Under the "Module" field, type "<strong>moodle</strong>" to get Moodle, "<strong>contrib</strong>" to get the contributions directory, or "<strong>mysql</strong>" to get the MySQL Admin module.<br>
118
7. Press the button: "<strong>OK</strong>" and everything should
122
<p>A dialog box should show all the files being downloaded, and after a while
123
you should have a complete copy of Moodle. After this first checkout, you
124
can fetch the latest updated files from the CVS server:</p>
126
<p> 1. Right-mouse-click on your Moodle folder (or any file) and select
127
"<strong>CVS Update</strong>". <br>
130
<p>After modifying files (you will note they change from green top red!),
131
you can commit them back to the CVS server like this:</p>
133
<p> 1. Right-mouse-click on your Moodle folder (or any file) and select
134
"<strong>CVS Commit...</strong>".<br>
136
2. In the dialog box, type a clear description of the changes you are
139
3. Click "OK". Your changes will be sent to the server.<br>
144
<p align="center">Good luck!</p>
149
<h3><a name="4.1" id="4.1"></a>4.1 Trunk development</h3>
151
<p>The Trunk of CVS is the main development version of Moodle. In CVS it is also known as the <span class="style4">HEAD</span>, or default branch.</p>
152
<p>Moodle developers try to keep this stable as possible, but as it usually contains new code it probably has bugs and small instabilities.</p>
153
<p>Every now and then we decide the product has enough features to make a release. At this time, the trunk is tagged with a <strong>MOODLE_XX_BETA</strong> tag (in case we ever want to roll back to that point) and a new branch is formed for the release, called <span class="style1">MOODLE_XX_STABLE</span>. </p>
154
<p>A Beta package is also released at this point - it's for testers who don't use CVS but want to test the latest features and report bugs.</p>
157
<h3><a name="4.2" id="4.2"></a>4.2 Stable branches for each release</h3>
159
<p>As soon as the stable branch <span class="style3">MOODLE_XX_STABLE</span> is created, development efforts will fork into two streams for a while. Some people may continue working on new features in the trunk for the next release, but most developers should be concentrating on using the current <span class="style1"><strong>STABLE</strong></span> branch and fixing bugs that are found in it. </p>
160
<p>You can switch your local copy of Moodle to the STABLE version using the following command in Unix from the root directory:</p>
161
<div class="commandline">cvs update -dP -r <span class="style1">MOODLE_XX_STABLE</span></div>
162
<p>After that, all the commands described above will apply to that stable version. To return to the trunk version just issue:</p>
163
<div class="commandline">cvs update -dPA</div>
164
<p>On Windows clients you should have a menu from which you can choose the branch. </p>
165
<p>Once the new STABLE branch really stabilises, a release can be declared. Packages are created for distribution and the branch will be tagged (by Martin) with a tag named: <strong>MOODLE_XXX</strong></p>
166
<p>Periodically, bug fixes in the STABLE branch should be merged into the trunk so that they become available in future versions of Moodle. A floating tag called MOODLE_XX_MERGED will be maintained to keep track of the last merge. The procedure for such a merge is as follows:</p>
169
<li>Get out the very latest trunk version.<br />
171
<div class="commandline">cvs update -dPA</div>
173
<li>Merge everything on the branch since the last merge, into your trunk version<br /><br />
174
<div class="commandline">cvs update -kk -j MOODLE_13_MERGED -j MOODLE_13_STABLE</div>
176
<li>Carefully watch the update logs for conflicts, and fix every file that you see with a conflict</li>
177
<li>Check the merged copy back into CVS trunk version<br />
179
<div class="commandline">cvs commit</div>
181
<li>Go back to the branch version<br /><br />
182
<div class="commandline">cvs update -dPr MOODLE_13_STABLE</div>
184
<li>Update the floating merge tag so that this process can be repeated next time<br /><br />
185
<div class="commandline">cvs tag -RF MOODLE_13_MERGED</div>
190
Finally, the values for <em>$version</em> in all the Moodle version.php files within the stable branch should not be updated at all if possible (except the last digit if necessary). The reason is that someone updating from a very stable version to the next very stable version could miss database upgrades that happened on the trunk. </p>
193
<h3><a name="4.3" id="4.3"></a>4.3 Feature branches for large changes </h3>
195
<p>Occasionally, there may be a very large feature that needs to be checked in so several people can work on it, but it is too unstable to be included in the main development trunk.</p>
196
<p>In these cases a short-term branch can be created to work on the feature, and then merged back into the main trunk as soon as possible. An example called <span class="style1"><strong>MOODLE_14_WIDGET</strong></span> branch can be seen in the above diagram.</p>
197
<p>If you need to do this for your new WIDGET feature, follow these steps:</p>
201
<li>Discuss with other developers to make sure it's necessary!</li>
202
<li>Make a new tag on the <strong>trunk</strong> (for all of moodle) called <strong>MOODLE_XX_WIDGET_PRE</strong>
204
<div class="commandline">cvs tag -R MOODLE_XX_WIDGET_PRE</div></li>
205
<li>Create your branch called <span class="style1"><strong>MOODLE_XX_WIDGET</strong></span>
207
<div class="commandline">cvs tag -Rb <span class="style1">MOODLE_XX_WIDGET</span></strong></div></li>
208
<li>Work in that branch until the feature is reasonably stable. Commit as necessary.
210
<div class="commandline">cvs commit</div></li>
211
<li>When ready, merge the whole branch into the trunk, fix conflicts, commit it to the trunk and then abandon the branch.
214
<div class="commandline">
215
<strong>cvs update -dPA</strong><br />
216
<strong>cvs update -kk -j <span class="style1">MOODLE_XX_WIDGET</span></strong><br />
217
<strong>cvs commit </strong></div>
226
<p align="center">Good luck, be careful and have fun!</p>
147
229
<p align="CENTER"><font size="1"><a href="." target="_top">Moodle Documentation</a></font></p>
148
<p align="CENTER"><font size="1">Version: $Id: cvs.html,v 1.12 2004/05/20 04:12:13 moodler Exp $</font></p>
230
<p align="CENTER"><font size="1">Version: $Id$</font></p>
added
removed
lang/en/docs/cvs.html
