incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <>
Subject Re: storing documentation in Subversion
Date Tue, 20 Dec 2005 10:08:18 GMT
Trustin Lee wrote:
> 2005/12/20, David Crossley <>:


>>The current operating principle is that we store all
>>source content in the official revision control system.
>>Some people have said that that is a dictate.
>>That includes everything: code, configuration files,
>>source content for docs, letters received, meeting minutes,
>>logos, everything.
> What I cannot understand is 'why ASF infra team is providing wiki' if we
> have to store all source content in the official RCS?  Does this mean what
> we documented in wiki can cause a problem?

This is the main sticking point in all the times I've seen this 
discussed on cocoon-dev, forrest-dev, site-dev and infra. We simply are 
not consistent between what we *say* and what we *do*.

Now I wonder where I've seen that before - oh yeah - every single client 
I ever worked with. I bet everyone here has the same experience. How 
come we haven't learnt our lessons?

What we need is a clear set of guidelines and a way to stick to them. So 
why is it that we are *supposed* to keep everything in SVN?

> We also store generated documentation in SVN.

At this point I will bring back Davids excellent list of reasons for 
storing in SVN and see how storing generated docs looks comparing to 
that list:

* History and origin of material.

No (but may be in the wiki/CMS)

* Recording who changed what and when and why.

No (but may be in the wiki/CMS)

* Ability to revert to any past revision of each resource.

No (but may be in the wiki/CMS)

* Easy archival, backup, and replication.

Of web site, yes, of history etc. no (its may be in the Wiki/CMS)

* Enable data mining, statistics, and relationships.

No (possibly in the Wiki/CMS)

* Enable anyone to review the past contributions
without contacting us.

Not through SVN, but through the CMS/Wiki

* Enable developers to use any editor tools that they
choose, to edit the content.

Possibly, depends on the Wiki/CMS's repository

By exploring how a Wiki/CMS can be used to satisfy most of the 
requirements David highlights we can see the confusion. A good Wiki/CMS 
will provide everything that David lists but it is not provided within 
the "standard" SVN framework.

Is it important *how* we satisfy the requirements?

That is probably for the Infra team, but last time it came up there the 
response was almost "go to site-dev and come back when you have a 
proposal". In other words (my interpretation, be careful ;-), as things 
currently stand we have the infrastructure to support sites generated 
from SVN. If you make it *easier* for us by using some other repository 
system, whilst still fulfilling all our requirements we'll consider it.

And there is the rub, we must make it *easier* for infra (oh and we must 
actually join the infra to team and help support the solution).

So what is the solution? A little more on that below.

First I want to highlight the last point in Davids list:

* Enable developers to use any editor tools that they
choose, to edit the content.

This is usually overlooked, because most of us have good Internet 
connections. However, it is, IMHO, very important. The argument for, or 
at least *my* argument for it, is that not everyone has Internet access 
all the time, not everyone has fast Internet access and some people pay 
a fortune for bandwidth. Therefore, an exclusively online tool limits 
contributions from such people.

The flip side of this is that Documentation is usually the easiest thing 
for newcomers to contribute to. There is no need to understand Apache or 
the internals of a project in order to make a valuable contribution to 
docs. However, forcing new users/devs to install SVN, check out the 
repository, work out the structure of the source files, make the edits, 
figure out how to create a patch, learn how to attach it to Jira and 
then post the patch is just too much.

So we need to make it easier for infra *and* easier for potential 
contributors (at every stage of their learning curve).

>>This makes it very easy to restore or replicate
>>the websites.

> ...  It would
> be great if there's some standardized tool many build tools support.

This is what we have been discussing (now stalled) over on the site-dev 
list. For a summary of discussion to to date see [1]. Site-dev is open 
to anyone, please come over and help with the technical aspects over 
finding a solution. Especially if you have experience of 
Wiki/CMS/Repository systems and you can help us realise this goal.

Lets keep discussions here around the requirements of such a system 
(incidentally [1] does not discuss any of the potential technical 
solutions, only the requirements).

> I always have imagined a web-based wiki application which stores its data in
> a certain directory in SVN repository.  Perhaps, we could create this kind
> of backend extension for our existing CMS.  

The problem is that we are unlikely to be able to create a solution that 
suits everyone. As I understand it infra don't care how the 
documentation is created as long as they can easily maintain the 
publishing framework, the ASF requirements for traceability are met and 
they are not expected support a wide range of CMS systems.

Sadly, everyone wants to use their own system (even within projects 
there is not always agreement). With the creation of zones for TLP's it 
is now possible for projects to "go it alone" using whatever CMS they 
want with whatever back-end they want (this has already happened in at 
least one project).

This could cause huge problems for infra - we have to come up with a 
solution *before* it becomes an unmaintainable problem. But how?

> Similarily, storing bugs and
> issues information could be stored in SVN repository, all in human readable
> text format.  Yes, this takes a lot of time.  Am I talking too ideally? :)

That's an interesting point. Issue tracking is another artifact that is 
not stored in SVN. Would it be useful to explore the justification for this?

Why is it that we don't need Jira issues replicated in SVN?



To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message