[Freeciv-Dev] Re: Documentation, Usability and Development

[Reinier Post <rp@xxxxxxxxxx>]

On Tue, Dec 04, 2001 at 10:46:49AM -0500, Andrew Sutton wrote:
> On Tuesday 04 December 2001 07:50 am, Reinier Post wrote:
> >   1a same repository, different branch?
> >      i don't know of any specific advantages - are there any?
> >   1b different CVS repository on cvs.freeciv.org?
> >      better from a sysadmin point of view, but you'd still be
> >      having the same sysadmins (and they read this list)
> >   1c CVS repository on sourceforge or berlios?
> >      that way, you'd stick with whatever facilities/policies they offer
> 
> i'd vote for sourceforge. it's a fairly comprehensive system and offers 
> pretty high availability (with recent exceptions noted :)

It also closed its source code recently - next thing you know they start
meddling with their policies.   There are alternatives, e.g. www.berlios.de
which run the SF source code.

> anyway, they offer 
> a pretty good database for bug tracking, feature tracking and task 
> management. also, support for documentation ;) and some other nice things 
> too. thousands of other projects have had success there. i see no reason why 
> freeciv shouldn't.

On Paul's hardware he can run and manage his own stuff.  However SF is
definitely smoother in some respects.  I'd prefer a combination.
I'd also prefer to leave the mailing lists where they are, we seem to
have better spam control.

> > 2 What to seed it with?
> >
> >   1a current Freeciv code
> >   1b nothing
> 
> two modules: freeciv1 that contains the current module and a placeholder for 
> what will eventually become freeciv2 (in whatever form that eventually turns 
> into).

I think the ideal CVS setup for Freeciv can be implemented on sourceforge
just as well as it can on cvs.freeciv.org.

> > 3 Where to put the documentation?
> >   1a in a dedicated corner on www.freeciv.org
> >   1b sourceforge/etc
> 
> i'd put it on freeciv.org. i think you can link to it from the sf docs 
> section. it would be nicer on freeciv. if you're talking about things like 
> the user manual, then i'd just include that as a separate product with the 
> freeciv project. that would let you get a) the program or b) the user manual 
> or c) the strategy guide - if one ever exists.

Yes.  www.freeciv.org ought to be in separate CVS modules - at the moment
it is in a single one.  This is on TODO.

> > 4 What does the documentation look like?
> >   Which tools to use to maintain it?
> 
> good question. i'm assuming you're talking about internals documentation. i'd 
> suggest html. its pretty much universal. as for an editing tool... hmm... 
> kword's okay. i don't know about abiword. ms word is really nice. whatever 
> medium needs to include support for embedded images (diagrams, etc) in case 
> somebody (like me) decides to break out UML for some of the design issues.

Yes, I was thinking about UML diagrams.  dia has some support but it
doesn't offer the integration with the C++ source tree that Visio offers.
THat would be nice to have ...

> > 5 Who gets CVS write access?
> >   5a function-related accounts
> >   5b personal accounts
> 
> compartmentalize the server and assign a maintainer for each module. that 
> person will maintain permissions for their own part of the project. this 
> would include:
>       - server
>       - metaserver
>       - common
>       - each ruleset
>       - each client
>       - ai
>       - graphics
>       - sounds
>       - build (somebody has to do the dirty work).

In general, a developer can update several modules (I don't think you
want to limit that to the assigned maintainer), and modules can
be updated by several developers, so they would have to be different
repositories, each with a write access list for users.

> > 6 Which system for bug reporting / patch tracking will be used?
> >   6a Freeciv's
> >   6b sourceforge/etc
 
> that's a good question too. bugzilla is probably more capable, but a little 
> more complicated. my personal preference would be to use sf... just to keep 
> everything together.
>
> andy

-- 
Reinier