OSCELOT   

 

OSCELOT is a community that creates innovative open source solutions for the challenges facing the eLearning community.

 

 

 

 

LOGIN
(admin only for now)

User:
Password:


 

Blackboard Launches EduGarage!
Read the press release...

Setting up a Project

Each approved project is given some space on the OSCELOT gForge site (http://projects.oscelot.org). This provides you with a range of tools to help you plan, develop and release your project, attract other members, track bugs and suggestions for new features. If you've not used gForge before it can seem a bit bewildering at first. This page aims to help you set up your first project. If you're not quite ready to take this step, you might want to join an existing group.

Creating a new project

This is easy - simply log in to the project site http://projects.oscelot.org and apply online. You'll need an account - if you haven't already joined, you'll need to register with OSCELOT first. After logging in click on the tab marked MY PAGE and use the link Register Project. Requests are moderated by members of the Project Board - usually you will get a decision within 24 hours. The purpose of moderation is to prevent the site filling up with lots of spurious adverts and phishing scams. If your project relates to e-Learning it should be approved!

When creating a new project you are asked to provide the following information:

  1. Full name of the project - give it a meaningful name - you have up to 40 characters so be as specific as possible (e.g. 'Discussion Board Grading Tool' is better than 'Grading Tool' or 'Grader').
  2. Purpose and Summary - this information is private and is used to help the board decide whether to approve your project. As such please be as detailed as possible.
  3. Choose a License - GNUthe default is the GNU General Purpose License, which is in line with OSCELOT's open source mission. More details about this license can be found on the free software foundation website. If you are unsure which to choose, look at those used by similar projects, or contact info@oscelot.org for advice!
  4. Public Description - this, along with the full name set earlier is visible to anyone interested in the project (be they potential users, or project partners). You have only 255 characters for this section, so make it snappy and 'sell' your project!
  5. Unix Name - each project stores files in a subdirectory of the main project site. For example if you decide that bert is the best name for your project, then it's full URL would be http://projects.oscelot.org/projects/bert. Hopefully you can come up with something more meaningful! Each Unix name must be unique and you have between 3 and 15 characters to play with. To keep things simple stick to lower case and avoid spaces and strange punctuation. Note that once set this cannot be changed, so choose it carefully and check your typing!

Basic configuration of your gForge project

Once your project is approved, you can log into the site. By default you'll see a set of tabs like this:
An example of a new project

Where this screenshot says "This is a sample project" you'll see the text you entered in the Public Description field above. You may well want to change this or other features such as which tabs are displayed. This involves switching to the to the ADMIN tab and clicking the Edit Public Info link. If there's something you want to do and no tab seems obvious then chances are the function can be accessed from this page.  :-)
Admin tab

Pause to note the location of the [Edit] link next to Trove Categorization (which we will discuss below) and then click the Edit Public Info link. This gives you access to the area where you can alter things - it's pretty self explanatory:
Edit Info page

(Note there's a handy Update button at the foot of the page not shown on this screenshot)

Making your project visible

Initially a project is only visible to you, so that you have a chance to prepare it for others. It's a bit like leaving a new course unavailable to students whilst staff prepare it. Rather than a specific 'make this project visible' flag, you have to use the more cryptic Trove Categorization - specifically the [Edit] link next to it. You'll then be prompted to provide information about the project to help other people decide what it's about and how well developed it is. The first few options are shown below:
Trove categorisation

 At the time of writing (Nov 2007) you'll need to specify the following fields:

  1. Intended Audience - The main class of people likely to be interested in this resource - options are things like Developers, End Users, etc.
  2. Development Status - An indication of the development status of the software or resource - options are things like Planning, Beta, Production, etc.
  3. License - License terms under which the resource is distributed - options are things like BSD, various flavours of GNU, etc.
  4. Programming Language - The language in which this program was written, or was meant to support- options are things such as Java, PHP - you probably won't be writing anything in Lisp or some of the other programming languages (and as someone who had to code in Common Lisp at one point, I say that advisedly).
  5. Platform - The environment required for this program- options are currently Blackboard, WebCT, etc., but more will be added soon.
  6. Topic -Topic categorisation  - options are things like Blackboard Building Blocks, WebCT Powerlinks, Simulations.
  7. Project Status this reflects the maturity of the project- options are Incubator, Provisional, or Community Release (more information)

Each field has three drop-down lists - you don't need to pick three for each one - just choose the best fit (and remember you can come back and edit this at any time). Why trove? Well think "Treasure trove". According to Wikipedia trove means means "old, hidden treasures" and so perhaps the idea that you browse through the trove to find treasure!

How other people can get involved

When a new project is created for you, you are given Administrator rights to the project. If you know of other people who want to get involved you can add them using the Add Users from List link. If you have made your project visible then anyone else can click on the [Request to join] link. You will then get an email which allows you to accept or reject their offer. You can also do this from within the project site - click on the ADMIN tab for your project. You should see a list of Project Members like this:
Sample Group Members page
If you accept the offer, you can choose the appropriate level of access to give this new member. The defaults are: a fellow Admin, a Senior Developer, a Junior Developer, a Documentation Writer or a Support Technician. As you may expect, these have different levels of access. You can determine what each role can and can't do for your project by editing the roles (using the Edit Role button), and even create new roles if you want different names (using the Add Role link).

Sharing the finished product with others

When you first apply for a project, it is only visible to you (and the Project Board). To allow other people to discover it and have it listed on the website, you need to categorise it using the trove. One thing people will certainly want to do is download the new tool. In your project there is a tab called FILES designed expressly for this purpose. This tab (though not necessarily all the content) is visible to everyone, once your project appears in the trove. As the sample project used has no files, the picture below shows the page from the Sign-up project (which does):A list of released files

You can organise the files you want to release under different headings - known as packages. This example shows a package called  production, further down the page is a second package (pre-release) which was never publicly released, but used to share alpha-versions of the code (a.k.a. buggy) between the developers. You could equally use your naming scheme to separate releases by operating system (e.g. if you need different versions for Windows or Linux), by the version of the associated software (e.g. Blackboard v6, WebCT Vista, Moodle 1.8.3) or topic (e.g. Help Guides, Install Files, etc).

For a Blackboard Building Block, you would typically release the code bundled up as a ZIP, JAR or WAR file. You can choose to make releases public or hidden. The latter are only visible to other members of the project (handy during testing stages). You can also attach release notes to alert users to what has changed. To add a file, you need to click on the Admin link on the FILES tab. You will be prompted for details of the  file - e.g. version number, release name, etc.  You are currently prompted for a lot of information which may not really seem very relevant (e.g. specifying the processor type). This is because we are still using some of the gForge defaults. If we can switch these off later, we will.

The column headed D/L shows the number of downloads of each release. I learnt that if you delete an old release you lose the associated number of downloads from your project total. If you want a highly rated project, you are advised to leave old releases available!

Project documentation

Your project has a DOCS tab, which you can use to manage documentation in a similar way you release the completed tool (see above).  This page is designed for internal use by the project - files here seem to be only visible to other members of your project. As such it is a great place to store and develop your notes from an initial brainstorming, functional specification documents, etc. Don't make the mistake I made, which was to put your help guides here - the people who really need them won't be able to read them. Instead you can release these to external users under a separate heading (package) from the FILES  tab or alternatively, build them on the project WIKI.

Managing the source code using Subversion

When you are just starting out, writing the code on your own, content versioning systems such as Subversion might seem overkill. Indeed they probably are, but you might want to get into the habit of using them early. When you are working with a team of developers, any of whom may potentially be making changes to the code then you need a system to manage it! You want to know if someone else is working on a particular bit of code, to be sure that you've got the latest version before you start testing or making more changes. You might even want to go back to a previous version later if you are supporting multiple versions (or just make a horrible mistake!) This is where Subversion (an open-source version control system) helps.

Subversion

Subversion is already installed on the OSCELOT project site. To make it work for you, you need to install a local client on the computer you use to write your code. If you are using an IDE such as Eclipse or netBeans, you should also install the appropriate plugin - this makes the whole process much easier.

To get started, you need to upload your code from your computer to your OSCELOT project site. The exact method for doing this varies, instructions below are taken from netBeans.

The strangely named SCM  tab provides you access to Subversion (it may not be enabled by default - see the basic configuration section above). The SCM tab

There are two ways to communicate with the repository:

1. Web Browsing You can browse stored versions of the code using the [Browse Subversion Repository] link at the right hand side of the page. This method allows download access only. Some examples follow using my SignUp tool (note exactly what you see if you try and reproduce this depends on whether I've made any further changes in the interim!). If you clicked on the [Browse Subversion Repository] link for the SignUp tool you'd see a page like this showing the repositories (usually there is only one):

initial repository
If you click the revision number (in this case 17 ) you will see details of this (the latest) version of the code, including any comments added by you or other developers when they copied their changes back to your OSCELOT project:

Details of the changes in this version

If instead, you'd clicked on the repository name (in this case SignUp/) you'd be able to navigate through the files with the speed of a, well web-browser...Files and folders in the source code

You can use this (admittedly clunky) method to navigate through individual source code files, handy if you want to see what people have been getting up to. If you are working on a project and need to access all the files, then this method would probably drive you mad. Happily there is another way...

2. DAV. Developers are able to mass upload new versions (or indicate to other users that you have 'checked out' a file for possible updates) using the distributed authoring and versioning (DAV) method.  This is where the software installed on your PC comes in handy. As it says, only project developers can access the SVN tree using DAV, as it requires you to provide a username and password of someone who has access to rights to the source code in the project area.

If you are connecting using a command line version of Subversion, you'll need to issue a command a bit like this:
svn checkout --username developername https://projects.oscelot.org/svn/signup

(swapping the terms username and developername for something appropriate). Note that this communication occurs over https and secondly, that the URL should be of the form https://projects.oscelot.org/svn/yourproject - currently the URL is wrongly reported as https://oscelot.org/svn/yourproject On some long-established projects you may also see reference to a learning objects URL (who kindly hosted the initial service for us). In all cases, use a URL beginning https://projects.oscelot.org/svn/ and just add the project's Unix name on to the end.

If you are using an IDE like netBeans, you can do it like this:

Importing your local Source Code from netBeans into Subversion for the first time

  1. Open your project in netBeans. Ensure you have installed the Subversion plugin - if you do you'll see a new menu called Subversion.
  2. Go to the Subversion menu and choose the option Import into Repository...

Initial Project Page

  1. A dialog box opens prompting you for details of the connection:

Connection details

  1. Enter details as shown above, replacing the text yourproject with the name of your project (e.g. bert) and replacing the text yourUsername with your OSCELOT username.
  2. Click the Next > button to connect to the repository:
Specifying details of the upload
  1. You can accept the default repository folder name (which will match that of your netBeans project) or click the Browse... button to select another folder or create a new one.
  2. Each upload requires a message, which is stored along with the changes. This is used by the development team to understand what's changed. As such typical messages are 'Initial Import', 'Fixed bug XX in loader', etc.
  3. Click Finish to upload your files. Note if it's a big project this can take some time. The progress is reported at the foot of the screen.

When you have finished, the project (Delicious in this example) is now shown with a database icon, showing it is synched to a repository. Watch what happens when you make changes to a file:
netBeans page showing changes in blue

In this example I have changed bb-manifest.xml and edit.jsp from the versions in the repository. This is shown in netBeans as it has automatically coloured the filenames in blue. Details are aslo shown in the Subversion pane at the foot of the screen (which you may need to add from the Window menu).

Commiting your changes back to Subversion

This is very easy:

  1. Go to the Subversion menu and choose Commit All Files:

Commiting

Checking out Files from Subversion into your IDE

This is equally simple (particularly if it is only you working on the files)
It is good practice to checkout files before you plan to change them - particularly if other people may be working on them.

  1. Open your project in NetBeans
  2. Go to the Subversion menu and choose the option Checkout...
  3. You' may need to specify the connection details again.

Updating your local files to incorporate changes made elsewhere (e.g. by other developers)

  1. Open your project in NetBeans
  2. Go to the Subversion menu and choose the option Update all Files

Note if you want to see what has changed before overwriting your local copies, use the Diff All Files command first.

Subversion also includes tools to help you resolve conflicts (e.g. if two people have made changes). This is beyond the scope of this demo, but plenty of information can be found on the Subversion website - including an excellent tutorial which is highly recommended.

Creating news items, mailing lists and discussion boards

Still to add this :-)

Using the bug-reports and feature-request trackers

These are very handy but I've still to say more...

Creating a project wiki

The project wiki is not enabled by default. To switch it on, click on the Edit Public Info link on the ADMIN tab. This gives you access to a basic wiki (don't expect to be able to upload images) but it's fine for creating a simple project home page.

Sample wiki page

You are strongly advised to follow the links to the Text Formatting Rules at the foot of any wiki page. It saves a lot of messing about with encoding trying to get bold, change heading styles, etc.

 

More Help

If you've any gForge tips you want to share please email them to info@oscelot.org.

 

gForgeYou might also want to look at the gForge documentation, which is (not surprisingly) hosted on the DOCS tab of the gForge gForge site.