Trustin Lee wrote:
2005/12/20, David Crossley <[EMAIL PROTECTED]>:
...
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?
Ross
[1] http://people.apache.org/~rgardler/site-dev/Site-Build.html
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
