<?xml version="1.0"?>
<document>

  <properties>
    <author>Ken McCullagh</author>
    <title>Administrators Guide</title>
  </properties>

  <body>

<section name="Introduction">
<p>
This document is intended to be a guide for administering projects on 
GForge. It is not intended to describe how to administer the 
GForge site itself. It is assumed that the reader will have also read 
the GForge Users Guide before reading this document.
</p>
</section>
<section name="What is GForge?">
<p>
GForge was developed by the Open Source community as an environment 
in which to host projects in a way that the code, documentation, binaries 
etc. were publicly accessible to all who wished to see them, and members of 
the public could use the software that was developed, and contribute feedback, 
bugs, ideas and suggestions, and even help to develop code/modules/documentation/resources 
for the software.
<br/><br/>

Traditionally it was used for software projects, although there is really no 
reason why it cannot be used to develop hardware or silicon projects also. 
<br/><br/>

Generally the world and it's mother have read access to the data associated 
with a project, with (some of) the developers having write access to the data. 
Usually there is a maintainer(s) of the code (the project leader or 
the person who registered the project) and contributers who email  
any changes to the code that they developed - bug fixes, additional functionality - 
which the maintainer adds to the code in the 
CVS tree upon verification that it was correct/clean/maintainable/useful.
</p>
</section>
<section name="What can GForge do for me?">
<p>
GForge can provide a centralized access point for several useful 
utilities and tools which could be used in a project. Some of these tools 
include:
<ol>
<li>A version control repository (CVS)</li>
<li>Mailing lists</li>
<li>Discussion forums</li>
<li>Bug tracking</li>
<li>A web interface to CVS</li>
<li>Task lists</li>
<li>A website which provides some statistics, including the members of the 
    project, the number of mailing lists, the number of CVS checkins/
    checkouts/adds, the number of items in the discussion forums, etc.</li>
</ol>
<br/><br/>
</p>
</section>
<section name="Setting up a new project">
<p>
In order to get a project up and running, you must be registered as a user 
of GForge. This is described in the GForge Users Guide.
</p>
</section>
<section name="Registering a new project">
<p>
It is quite straightforward to register a new project on GForge. The 
steps involved are:
<ol>
<li>Login to GForge</li>
<li>Select Register New Project from the menu on the left hand side of the 
    page.</li>
<li>Fill in the Full Name, Unix Name, Project Purpose and Summarization 
    fields (paying attention to the restrictions listed on the page) and 
    select a license type.</li>
<li>Click Proceed with this registration and assuming that all the details 
    are correct, and that the name is unique, the project will be accepted 
    pending approval. If there are details missing, or other errors, you will 
    be informed of the problem.</li>
<li>Assuming that the project is approved, you will be sent back an email 
    confirming that this is the case, and listing the website, cvsroot etc 
    of the project you created. It will take some time for the cvsroot to be 
    created - usually by an overnight cronjob.</li>
</ol>
<br/><br/>
Once you have received the email confirming the project has been accepted, 
you will be able to find your project through the search box by entering
your project's name or details. Clicking on the project link provided will 
bring you to the project summary page, the default starting point for all 
the project administration.
</p>
</section>
<section name="Administering a new project">
<p>
This section provides an oversight on how to set up the GForge utilities 
so that they can be used by your project once it has been approved. 
Typically the cvs space will have been allocated by the morning after 
the confirmation email is sent to the project requester. In order to get the 
project into a useable state, the project administrator will need to perform 
some steps.
</p>
</section>
<section name="CVS repository">
<p>
If the project does not already have a CVS repository in place (eg if an 
existing project is being added to GForge mid-life, rather than a brand 
new project being started) the CVS repository will need to be set up. 
There are plenty of resources on CVS around so this document will not attempt 
to describe how to use CVS, but will provide just enough information to get 
started.

<br/><br/>

</p>
</section>
<section name="Setting up the CVSROOT">
<p>

Before any CVS operations can be carried out, the CVSROOT environment 
variable must be set in the command shell you are using, or in whatever 
CVS GUI you are using, such as WinCVS. 
</p>
</section>
<section name="Setting your .rhosts file correctly">
<p>


In your UNIX home directory there exists a file called <code>.rhosts</code>. This file 
requires special permissions, namely :<br/>
<source><![CDATA[

	-rw-r--r--   .rhosts
]]></source>


If this is not correct, you will encounter problems trying to access CVS. If 
this file is not present, it must be created.
<br/><br/>

Secondly, your .rhosts file must contain the name of the machine(s) from 
which you are accessing CVS. The format of the file is as follows:<br/>
<source><![CDATA[

	machine1 username
	machine2 username
]]></source>

<br/>

It is recommended that fully qualified domain names are used, or IP addresses, 
as this seems to solve problems arising due to machines in different offices 
accessing each other. The last line of the file may optionally be<br/>
<source><![CDATA[

	+ username 
]]></source>

<br/>

to allow UNIX (not Linux) machines to use wildcard matching to allow access 
from all hosts on the network. This does NOT work on Linux, which is what 
the GForge server runs. Also, if the wildcard entry is before the machine
you wish to use, then it will not work either.
<br/><br/>

</p>
</section>
<section name="Creating the CVS repository">
<p>
Once CVSROOT has been set, the base entry for CVS can be added. This is the 
top level for the directory structure of the repository.
<br/><br/>

This is done using the cvs import command. The following steps show how it 
can be done.<br/>
<source><![CDATA[

	$ cd &amp;lt;top of tree&amp&gt;>;
	$ cvs import <&amp&lt;module-name&ampgt; &lt;vendor-tag&gt; &lt;release-tag&gt;

]]></source>
<br/>

e.g. suppose we wish to import a directory structure called myproject, which was 
obtained from "customer" and is labelled "releaseone" we would do:<br/>
<source><![CDATA[
	$ cd path/to/myproject
	$ cvs import myproject customer releaseone
]]></source>

<br/>

If we wanted to create a clean, new directory structure called mynewproject we could 
do something like this.<br/>
<source><![CDATA[
	$ mkdir mynewproject
	$ cd mynewproject
	$ cvs import mynewproject mycompany start
]]></source>
<br/>

This is pretty much all that has to be done to start up the CVS repository - 
after this the repository can be used in the normal way. It is also possible 
to import several modules to the same CVS repository. e.g.<br/>
<source><![CDATA[
	$ cd path/to/src
	$ cvs import src S3 src0
	$ cd path/to/docs
	$ cvs import docs S3 docs0
]]></source>

<br/>

But as was said earlier, this is not the place to provide a complete
introduction to CVS.  Go out and find some of the abundant documentation that
is available for it on the web and elsewhere. Most importantly, if you run
into a problem with CVS, it is NOT the GForge administrator's fault so
don't go running to them every time. Try to figure it out yourself or go
looking for help on CVS related news groups.

</p>
</section>


</body>
</document>
	
