Documentation improvements for CVS and developing in general

This commit is contained in:
moodler
2002-12-10 06:17:31 +00:00
parent 0c8106d326
commit 8736d429d4
4 changed files with 222 additions and 124 deletions
+1
View File
@@ -16,6 +16,7 @@
<LI><A TARGET="main" HREF="upgrade.html">Upgrading</A>
<LI><A TARGET="main" HREF="teacher.html">Teacher Manual</A>
<LI><A TARGET="main" HREF="developer.html">Developer Manual</A>
<LI><A TARGET="main" HREF="cvs.html">Using CVS</A>
<LI><A TARGET="main" HREF="future.html">Future</A>
<LI><A TARGET="main" HREF="credits.html">Credits</A>
<LI><A TARGET="main" HREF="licence.html">License</A>
+1
View File
@@ -15,6 +15,7 @@
<LI><A TARGET="main" HREF="upgrade.html">Upgrading</A>
<LI><A TARGET="main" HREF="teacher.html">Teacher Manual</A>
<LI><A TARGET="main" HREF="developer.html">Developer Manual</A>
<LI><A TARGET="main" HREF="cvs.html">Using CVS</A>
<LI><A TARGET="main" HREF="future.html">Future</A>
<LI><A TARGET="main" HREF="credits.html">Credits</A>
<LI><A TARGET="main" HREF="licence.html">License</A>
+145 -83
View File
@@ -1,87 +1,149 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Moodle Docs: How to use CVS</TITLE>
<LINK REL="stylesheet" HREF="../theme/standard/styles.css" TYPE="TEXT/CSS">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H2>How to use CVS</H2>
<BLOCKQUOTE>
<P>CVS is the Concurrent Versioning System. It's a commonly used way
of storing source code because it keeps versions of all files so
that nothing is ever lost, and usage by different people is tracked.</P>
<P>To use Moodle's CVS archive (as a developer) from a Unix machine, you first
need to have an account on <a href="http://www.sf.net/">Sourceforge</a>. For
the example, let's assume your username is <strong>myusername</strong> and your
password is <strong>mypassword</strong>. Secondly, you need to contact me (<A
HREF="http://dougiamas.com/">Martin Dougiamas</A>) to get write access
to particular directories.</P>
<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>
<P>Sourceforge CVS uses ssh as a transport layer for security, so you will have
to set this CVS_RSH environment variable in your Unix shell:</P>
<blockquote>
<pre><strong>setenv CVS_RSH ssh</strong> (for csh, tcsh etc)</pre>
<pre><strong>export CVS_RSH=ssh</strong> (for sh, bash etc)</pre>
</blockquote>
<p>It's best to put this in your .bashrc or .cshrc so you don't have to type it
all the time. Then, check out Moodle using this (all one line): </p>
<blockquote>
<pre><strong>cvs -z3 -d:ext:[email protected]:/cvsroot/moodle co moodle</strong></pre>
</blockquote>
<p>Don't try to do run this first CVS command into an existing moodle directory
- start fresh with a new directory.</p>
<p>Note that you will be prompted for <strong>mypassword</strong> with each CVS
command. To avoid this, follow the <a href="http://sourceforge.net/account/editsshkeys.php">Sourceforge
directions about using authorized keys</a>.</p>
<p>Now, you should have a new 'moodle' directory. You can rename it and move it
around if you like. Go into it: </p>
<blockquote>
<pre><strong>cd moodle </strong></pre>
</blockquote>
<p>All the latest Moodle files should be in there. You can now change files in
your copy. To compare your files against the main CVS copy on the server use
cvs diff, eg: </p>
<blockquote>
<pre><strong>cvs diff -c config-dist.php
<html>
<head>
<title>Moodle Docs: How to use CVS</title>
<link rel="stylesheet" href="../theme/standard/styles.css" type="TEXT/CSS">
</head>
<body bgcolor="#ffffff">
<h2>Using CVS to access and update Moodle source code</h2>
<blockquote>
<p>CVS is the Concurrent Versioning System. It's a commonly used way of storing
source code because it keeps 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 this case, at <a href="http://www.sf.net/">Sourceforge</a>).
</p>
<p>To use Moodle's CVS archive (as a developer) from a Unix machine, you first
need to have an account on <a href="http://www.sf.net/">Sourceforge</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>.
Once you have an account, you need to contact me (<a
href="http://dougiamas.com/">Martin Dougiamas</a>) to get write access to particular
directories.</p>
<p>To avoid being prompted for <strong><font color="#990000">mypassword</font></strong>
every time you run a CVS command, follow the <a 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>
<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. Below are instructions for Unix and Windows systems.</p>
<h3>1. Using CVS on Unix</h3>
<blockquote>
<p>Sourceforge CVS uses ssh as a transport layer for security, so you will
have to set this CVS_RSH environment variable in your Unix shell:</p>
<blockquote>
<pre><strong>setenv CVS_RSH ssh</strong> (for csh, tcsh etc)</pre>
<pre><strong>export CVS_RSH=ssh</strong> (for sh, bash etc)</pre>
</blockquote>
<p>It's best to put this in your .bashrc or .cshrc so you don't have to type
it all the time. Then, check out Moodle using this (all one line): </p>
<blockquote>
<pre><strong>cvs -z3 -d:ext:[email protected]:/cvsroot/moodle co moodle</strong></pre>
</blockquote>
<p>Don't try to do run this first CVS command into an existing moodle directory
- start fresh with a new directory.</p>
<p>Note that you will be prompted for <strong><font color="#990000">mypassword</font></strong>
for each command unless you set up <a href="http://sourceforge.net/account/editsshkeys.php">authorized
keys</a></p>
<p>Now, you should have a new 'moodle' directory. You can rename it and move
it around if you like. Go into it: </p>
<blockquote>
<pre><strong>cd moodle </strong></pre>
</blockquote>
<p>All the latest Moodle files should be in there. You can now change files
in your copy. To compare your files against the main CVS copy on the server
use cvs diff, eg: </p>
<blockquote>
<pre><strong>cvs diff -c config-dist.php
cvs diff -c lang</strong></pre>
</blockquote>
<p>To fetch the latest updates from the server use: </p>
<blockquote>
<pre><strong>cvs update -dP</strong> </pre>
</blockquote>
<p>To copy your new files back to the server you would do: </p>
<blockquote>
<pre><strong>cd lang/ca
</blockquote>
<p>To fetch the latest updates from the server use: </p>
<blockquote>
<pre><strong>cvs update -dP</strong> </pre>
</blockquote>
<p>To copy your new files back to the server you would do something like:
</p>
<blockquote>
<pre><strong>cd lang/ca
cvs commit</strong> </pre>
</blockquote>
<p>You will be prompted to add some comments (depends on your default text editor)
... add a comment and close the editor ... the files will be sent to Sourceforge
and stored. Done! </p>
<p>To save more time you can put default arguments into a file called .cvsrc in
your home directory. For example, mine contains: </p>
<blockquote>
<pre><strong>diff -c
</blockquote>
<p>You will be prompted to add some comments (depends on your default text
editor) ... add a meangingful comment and close the editor ... the files
will be sent to Sourceforge and stored. Done! </p>
<p>To save more time you can put default arguments into a file called .cvsrc
in your home directory. For example, mine contains: </p>
<blockquote>
<pre><strong>diff -c
update -dP</strong> </pre>
</blockquote>
<p>Try 'cvs help' for more details ... </p>
<p>&nbsp;</p>
</blockquote>
<h3>2. Using CVS on Windows</h3>
<blockquote>
<p>These instructions are based on notes provided by Mitsuhiro Yoshida &lt;[email protected]&gt;.</p>
<p>Firstly, download and install WinCVS.</p>
<blockquote>
<p><a href="https://sourceforge.net/project/showfiles.php?group_id=10072">https://sourceforge.net/project/showfiles.php?group_id=10072</a></p>
</blockquote>
<p>Secondly, download sfsetup for SourceForge ssh access, install it and reboot
Windows.</p>
<blockquote>
<p><a href="http://sourceforge.net/projects/sfsetup/">http://sourceforge.net/projects/sfsetup/</a></p>
</blockquote>
<p>Next, configure WinCVS. Launch it, and select Admin -&gt; Preferences.
Then change them as follows:</p>
<blockquote>
<p> [General]<br>
<strong>CVSROOT data</strong>:<br>
<strong>Authentication</strong>: ssh<br>
<strong>Path</strong>: /cvsroot/moodle<br>
<strong>Host address</strong>: cvs.moodle.sourceforge.net<br>
<strong>User name</strong>: <font color="#990000">myusername</font><br>
<strong>CVSROOT</strong>: <font color="#990000">myusername</font>@cvs.moodle.sourceforge.net:/cvsroot/moodle</p>
<p>[Globals]<br>
<strong>Checkout rad-only</strong>: uncheck<br>
<strong>Supply control when adding files</strong>: check<br>
<strong>Quiet mode</strong>: uncheck<br>
<strong>TCP/IP compression</strong>: check and select 9<br>
<strong>Dirty files support</strong>: check<br>
<strong>Prune(remove) empty directories</strong>: check<br>
<strong>Disable splash screen</strong>: uncheck</p>
</blockquote>
<p>Congratulations, WinCVS is set up. Now, you should check out a complete
working copy of the Moodle course code:</p>
<ol>
<li>Select 'Create -&gt; checkout'</li>
<li>For the setting 'Module name and path on the server&quot;, type &quot;moodle&quot;,
then click OK.</li>
<li>Type in <strong><font color="#990000">mypassword</font></strong> and
press Enter in the DOS window.</li>
</ol>
<p>After this first checkout, you can fetch updated files from the CVS server
like this:</p>
<ol>
<li> Select folders or files you want to update</li>
<li>Press right mouse button and select '<strong>Update selection</strong>'</li>
<li>Press OK button</li>
<li>Type in <strong><font color="#990000">mypassword</font></strong> and
press Enter in the DOS window.</li>
</ol>
<p>After modifying files, you can commit them back to the CVS server like
this:</p>
<ol>
<li>Select folders or files you want to commit</li>
<li>Press right button and select '<strong>Commit selection</strong>'</li>
<li>Press OK button</li>
<li>Type in a meaningful comment and press OK button.</li>
<li>Type in <strong><font color="#990000">mypassword</font></strong> and
press Enter in the DOS window.</li>
</ol>
</blockquote>
<p>&nbsp;</p>
<p align="center">Good luck!</p>
<p>&nbsp;</p>
</blockquote>
<p>Try 'cvs help' for more details ... </p>
<P>&nbsp;</P>
</BLOCKQUOTE>
<P ALIGN="CENTER"><FONT SIZE="1"><A HREF="." TARGET="_top">Moodle Documentation</A></FONT></P>
<P ALIGN="CENTER"><FONT SIZE="1">Version: $Id: features.html,v 1.2 2001/12/09
10:34:19 martin Exp $</FONT></P>
</BODY>
</HTML>
<p align="CENTER"><font size="1"><a href="." target="_top">Moodle Documentation</a></font></p>
<p align="CENTER"><font size="1">Version: $Id: features.html,v 1.2 2001/12/09
10:34:19 martin Exp $</font></p>
</body>
</html>
+75 -41
View File
@@ -1,30 +1,30 @@
<HEAD>
<TITLE>Moodle Docs: Developers Manual</TITLE>
<LINK REL="stylesheet" HREF="../theme/standard/styles.css" TYPE="TEXT/CSS">
</HEAD>
<head>
<title>Moodle Docs: Developers Manual</title>
<link rel="stylesheet" href="../theme/standard/styles.css" type="TEXT/CSS">
</head>
<BODY BGCOLOR="#FFFFFF">
<H2>Developers Manual</H2>
<P>This document describes some of Moodle's design and how you can contribute.</P>
<P>Sections in this document:</P>
<OL>
<LI><A HREF="#architecture">Moodle architecture</A></LI>
<LI><A HREF="#contribute">How you can contribute</A>
<body bgcolor="#FFFFFF">
<h2>Developers Manual</h2>
<p>This document describes some of Moodle's design and how you can contribute.</p>
<p>Sections in this document:</p>
<ol>
<li><a href="#architecture">Moodle architecture</a></li>
<li><a href="#contribute">How you can contribute</a>
<ul>
<li><A HREF="#activities">Learning activities</A></li>
<li><A HREF="#themes">Themes</A></li>
<li><A HREF="#languages">Languages</A></li>
<li><A HREF="#database">Database Schemas</A></li>
<li><a href="#activities">Learning activities</a></li>
<li><a href="#themes">Themes</a></li>
<li><a href="#languages">Languages</a></li>
<li><a href="#database">Database Schemas</a></li>
<li><a href="#courseformats">Course formats</a></li>
<li><a href="#doc">Documentation and articles</a></li>
<li><a href="#bugs">Participating in the bug tracker</a></li>
</ul>
</LI>
</OL>
<P>&nbsp;</P>
<H3><a name="architecture"></a>1. Moodle architecture</H3>
<P>From a system administrator's perspective, Moodle has been designed according
to the following criteria:</P>
</li>
</ol>
<p>&nbsp;</p>
<h3><a name="architecture"></a>1. Moodle architecture</h3>
<p>From a system administrator's perspective, Moodle has been designed according
to the following criteria:</p>
<ol>
<li><strong>Moodle should run on the widest variety of platforms</strong><br>
<br>
@@ -79,15 +79,15 @@
interface formatting (so that it can be integrated visually into other web sites).</li>
</ol>
<p>&nbsp;</p>
<H3><a name="contribute" id="contribute"></a>2. How you can contribute</H3>
<P>As mentioned above, Moodle has a number of features that are modular. Even
if you are not a programmer there are things you can change or help with.</P>
<P><strong><a name="activities" id="activities"></a>Learning Activities</strong></P>
<h3><a name="contribute" id="contribute"></a>2. How you can contribute</h3>
<p>As mentioned above, Moodle has a number of features that are modular. Even
if you are not a programmer there are things you can change or help with.</p>
<p><strong><a name="activities" id="activities"></a>Learning Activities</strong></p>
<blockquote>
<p>These are by far the most important modules, and reside in the 'mod' directory.
There are seven default modules: assignment, choice, forum, journal, quiz, resource,
and survey. Each module is in a separate subdirectory and consists of the
following mandatory elements (plus extra scripts unique to each module):</p>
There are seven default modules: assignment, choice, forum, journal, quiz,
resource, and survey. Each module is in a separate subdirectory and consists
of the following mandatory elements (plus extra scripts unique to each module):</p>
<ul>
<li>mod.html: a form to set up or update an instance of this module</li>
<li>version.php: defines some meta-info and provides upgrading code</li>
@@ -113,18 +113,42 @@
</ul>
</li>
<li>Lastly, each module will have some language files that contain strings
for that module. See below.<br>
</li>
for that module. See below.</li>
</ul>
<p>The easiest way to start a new learning activity module is to use the template
in <strong><a href="http://moodle.com/mod/newmodule_template.zip">mod/newmodule_template.zip</a>.</strong>
Unzip it and follow the README inside. </p>
<p>You might also like to post first in the <a href="http://moodle.com/mod/forum/view.php?id=44" target="_top">Activities
modules forum on Using Moodle</a>.</p>
<p>&nbsp;</p>
</blockquote>
<p> <strong><a name="themes" id="themes"></a>Themes</strong></p>
<blockquote>
<p>Themes (or skins) define the look of a site. A number of simple themes are
provided in the main distribution, but you may want to copy one of these and
customise it to suit your own needs (eg local logo, colours, styles, graphics
etc)</p>
<p>Each theme is in a subdirectory of the &quot;theme&quot; directory. You can
copy the &quot;standard&quot; theme as a template.<br>
etc). Each theme is in a subdirectory of the &quot;theme&quot; directory.
You can copy the &quot;standard&quot; theme or any other theme as a template
for your own.</p>
<p>Here is what each of the files does:</p>
<ul>
<li><strong>config.php</strong>: defines your theme colours used throughout
the site</li>
<li><strong>styles.php</strong>: the style sheet, containing CSS definitions
for standard HTML elements as well as many Moodle elements.</li>
<li><strong>header.html</strong>: Included at the top of each page. This is
what you need to edit to add a logo at the top of pages, for example.</li>
<li><strong>footer.html</strong>: Included at the bottom of each page.</li>
</ul>
<p>Note that Moodle upgrades <em>may</em> break themes slightly, so check the
release notes carefully if you are using a custom theme.</p>
<p>In particular, Moodle 2.0 will have a completely new display system, based
on a XSL transformations of XML output from Moodle. It is likely that the
themes for this will be a completely different format, but the advantage will
be a much higher possible degree of customisation (including moving elements
around the page).</p>
<p>More discussion about this in the <a href="http://moodle.com/mod/forum/view.php?id=46">Themes
forum on Using Moodle</a>.<br>
</p>
</blockquote>
<p><strong><a name="languages" id="languages"></a>Languages</strong></p>
@@ -167,6 +191,15 @@
<p>and for modules:</p>
<p>helpbutton(&quot;forumtypes&quot;, &quot;Forum types&quot;, &quot;forum&quot;);</p>
</blockquote>
<p>Note that you can edit languages online, using the administration web tools
under &quot;Check this language&quot;. This makes it easy to not to only create
new languages but to refine existing ones. If you are starting a new language,
please contact me, <a href="http://dougiamas.com/">Martin Dougiamas</a>. </p>
<p>You might also like to post in the <a href="http://moodle.com/mod/forum/view.php?id=43" target="_top">Languages
forum on Using Moodle</a>. </p>
<p>If you are maintaining a language an ongoing basis, I can give you <a href="cvs.html">CVS
write access to the Moodle source code</a> so that you can directly maintain
the files.</p>
</blockquote>
<p><br>
<strong><a name="database" id="database"></a>Database Schemas</strong></p>
@@ -182,12 +215,13 @@
and inside the <strong>db</strong> subdirectory of each module.</p>
<p>Currently, only MySQL is supported because that's what I know. If you are
familiar with another database (especially open source databases) and are
willing to help port the MySQL schema, please get in contact with me (<a href="mailto:martin@moodle.com">martin@moodle.com</a>).</p>
willing to help port the MySQL schema, please get in contact with me (<a href="http://dougiamas.com/">Martin
Dougiamas</a>).</p>
</blockquote>
<p>&nbsp;</p>
<p><strong><a name="courseformats" id="courseformats"></a>Course Formats</strong></p>
<blockquote>
<p>Moodle 1.0 supports three different course formats: weekly, topics and social.
<p>Moodle 1.x supports three different course formats: weekly, topics and social.
</p>
<p>These are a little more connected to the rest of the code (and hence, less
&quot;pluggable&quot;) but it is still quite easy to add new ones.</p>
@@ -199,8 +233,8 @@
<p><strong><a name="doc" id="doc"></a>Documentation and articles</strong></p>
<blockquote>
<p>If you feel like writing a tutorial, an article, an academic paper or anything
else about Moodle, please do! Put it on the web and make sure you include
links to <a href="http://moodle.com/">http://moodle.com/</a></p>
else about Moodle, please do! </p>
<p>Put it on the web and make sure you include links to <a href="http://moodle.com/">http://moodle.com/</a></p>
</blockquote>
<p>&nbsp;</p>
<p><strong><a name="bugs" id="bugs"></a>Participating in the bug tracker</strong></p>
@@ -230,8 +264,8 @@
<blockquote>
<p>&nbsp;</p>
</blockquote>
<P ALIGN="CENTER"><FONT SIZE="1"><A HREF="." TARGET="_top">Moodle Documentation</A></FONT></P>
<P ALIGN="CENTER"><FONT SIZE="1">Version: $Id: developer.html,v 1.2 2001/12/09
10:34:19 martin Exp $</FONT></P>
<p align="CENTER"><font size="1"><a href="." target="_top">Moodle Documentation</a></font></p>
<p align="CENTER"><font size="1">Version: $Id: developer.html,v 1.2 2001/12/09
10:34:19 martin Exp $</font></p>
</BODY>
</body>