[Xerte] Developer documentation

[Nicola Wilkinson]

Hi Patrick,

Thanks for the answer to many of my questions - consider them documented - a list is as good a place as any.

I think you need to get the licence sorted, in light of this OSS-Watch (http://www.oss-watch.ac.uk/) have been very helpful in relation to issues like this which I faced with our open source project. You can always tell them I sent you, I don't mind.

I will have a look to find the database scripts (at the moment everything is still files) - What I do and the order in which I do things I will feed back to you. 

The air speed of a swallow is approximately 11 meters per second or roughly 24 miles and hour (see I was still reading)!

Nic

-----Original Message-----
From: xerte-bounces at lists.nottingham.ac.uk [mailto:xerte-bounces at lists.nottingham.ac.uk] On Behalf Of Patrick Lockley
Sent: 14 May 2009 13:56
To: Xerte discussion list
Subject: RE: [Xerte] Developer documentation

Hello,

First off

There are two xertes. To filter some mud from the water.

Desktop Xerte - A developer tool flash based application that can run on
a windows PC to develop flash and xml to be deployed on a web server.
This is the EXE Version. The exe version does not have a database. It is
completely separate and does not care about the Xerte Online Toolkits
version. Honestly, it never writes or anything. They can be used
completely separately.

(Just in case cross wires by exe, I don't mean eXe, but executable.)

Xerte Online Toolkits - A web based version of the Xerte wizards feature
available to people working directly on a web server. This is at present
its usage. The site is however almost completely modularized and could
support other versions of other templates if someone wants to. I think
only the export functions aren't modularized. 

Bringing together a few emails into one

1) The reason we don't have a full GPL license is (at the moment)
because I wanted to explicitly offer my personal thanks to the
developers of the three other PHP scripts that help the site work. To
many open source projects just bring together loads of other code and
pass it off without proper attribution. On the first page of the
installer it does thank these people. One of these pieces of code also
lacks a license (he just wants you to send him a copy of what you do),
so I am not sure legally if we can offer it as GPL anyways. We could
possibly remove this code from the install and offer a guaranteed GPL
version, but we'd lose some functions and have two installers to deal
with.

2) There are no instructions for any one downloading from the SVN as to
what the database script code is, where it is and how to apply this.

Correct, but there is an installer and a set up folder containing a file
called basic.sql which does the vast majority of the database creation
(it could be run separately with some minor mods). There isn't a script
to do this generically (if you ignore the fact that the installer does
all of it) as some of the database settings are specific to each
install.

If you want to install toolkits, I would suggest downloading the
installer from http://www.nottingham.ac.uk/xerte rather than using the
SVN. You can run a local version very easily if you're on a PC by
choosing the XAMPP installer. If you're not using a localhost install,
you can choose the full install option. There is someone at Loughborough
who has done this already and I am guessing you know who so he may be
able to demo?

We have worked on the basis that to encourage the use of the project an
installer makes more sense than forcing people to work out which bits of
code to change here and there. So far we've had no really complaints
about the installer, and most people appear to have installed it without
any issues.

3) In addition have you any coding standards that are being followed. I
ask only because I have noted that you are using the abbreviated php tag
(<?) rather than the more commonly accepted tag (<?php).

True, although in my defence and to counter any accusations of laziness,
I didn't realise this was a problem until I pretty much finished the
installer (I was working on the basis long tags are a bit obsolete). The
project has gone through a variety of phases, and a lot of the initial
work was done before it moved to become open source. So this is somewhat
of a legacy admittedly, but it is only a matter of doing a find and
replace on the files.

As for standards......

4) I too am a fan of the phpdoc standard, built in a similar manor to
the Javadoc. As for Xerte from examining the code the use of this is
sporadic

As for this, other than 1-2 pages where I know the commenting isn't
ideal, I spent two whole weekends commenting up the code to phpdoc
standard. I've even done the javascript to the same standard (even
though it was futile as JS DOC uses some XML format instead). If they
aren't at PHP doc standards, then I have no plans to change them as I
will be shooting myself to get over how stupid I'll feel.

I don't have any code standards or preferences, other than to keep to
PHPdoc now I erm have done it, try to comment every If statement (give
or take a few where its obvious). I've spent too much time myself bogged
down in open source code that basically isn't as its written badly and
without comments. I've tended to use very basic code and simple
functional patterns so as to make the code as modifiable and
customisable as possible.

I would be surprised if someone said the Xerte Online Toolkits code was
awkward. I've been pretty anally retentive in terms of file names,
naming conventions and folder structures. The website_code folder
contains all the website code, in side that are folders called php,
scripts, styles.... Admittedly it's not a guide per say, but I would say
its fairly obvious. As to finding out what calls what - I recommend
fiddler. It is amazing.

I've attached a presentation I gave on the code workings. I think it
might cover some of the points you've raised.

Is anyone still reading? Spot quiz time? What is the air speed velocity
of a swallow?

In terms of contributions from other users, so far it's mostly been bug
fixes (we release a weekly list of fixed bugs and modifications - this
week is free of them so far), but we have received 4 or 5 changes from
organizations and colleges where the system is running.

Every time I have fixed an individual bug, I have offered to that person
scope for the creation of a Xerte Online Toolkits developer's list / sys
admin list, or a desire for increased developer documentation. 

No one has ever replied.

As a developer, I could go write the manuals, but in terms of sheer
pragmatism, do people think the time spent on that would be commensurate
with the resources returned?

I would love to think people would be interested in doing so, but would
prefer to establish some sort of steering group before continuing to
create documentation. And also as the benevolent dictator (though I'd
see it more as anarchist) I find it hard to work out what people want as
often I fix things and hear nothing more. I wrote in a load of extra
code to make moodle integration possible, and then when we did moodle
integration we took it all out again. Nice.

If you'd be interested (or anyone else still here) would be interested
in this then I would be keen to work towards something.

Apologies for the essay, and it's far too large for me to proof read. So
I'll call this reply open source and people can correct my spelling at a
later date.

Thanks for the interest though. I am grateful for all feedback.

Pat