You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@incubator.apache.org by David Crossley <cr...@apache.org> on 2005/12/20 04:10:46 UTC
storing documentation in Subversion
This is a topic that i often hear, not only at new projects.
People are not sure what needs to be stored in svn and why.
A while ago, Noel raised the issue on the infra@ list. [1]
Unfortunately not much follow-up. So i wonder if we can
resolve it here and then document the outcome.
I see at least three issues. They are probably related.
-----------
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.
It would be useful to list the reasons for doing that
and the benefits. Here are some to get started:
* History and origin of material.
* Recording who changed what and when and why.
* Ability to revert to any past revision of each resource.
* Easy archival, backup, and replication.
* Enable data mining, statistics, and relationships.
* Enable anyone to review the past contributions
without contacting us.
* Enable developers to use any editor tools that they
choose, to edit the content.
Is there also a requirement that we need to track
our assets by virtue of being a Foundation?
-----------
We also store generated documentation in SVN.
This makes it very easy to restore or replicate
the websites.
There are stalled discussions at Infra site-dev list
about alternatives to that process.
-----------
With the advent of new documentation management tools
(e.g. Lenya, JackRabbit, Daisy) and their potential
use by ASF projects for their project documentation,
we are seeing questions about how to enable the
storage of the sources for documentation.
In my opinion we should continue to use SVN.
What do others think?
-David
[1]
>From: Noel J. Bergman
To: infrastructure@a.o
Date: Thu, 20 Oct 2005 12:47:16 -0400
Subject: Official source content in CMS other than CVS/SVN?
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: storing documentation in Subversion
Posted by Steven Noels <st...@outerthought.org>.
On 20 Dec 2005, at 04:10, David Crossley wrote:
> With the advent of new documentation management tools
> (e.g. Lenya, JackRabbit, Daisy) and their potential
> use by ASF projects for their project documentation,
> we are seeing questions about how to enable the
> storage of the sources for documentation.
>
> In my opinion we should continue to use SVN.
You're talking about
http://opensource2.atlassian.com/confluence/oss/pages/viewpage.action?
pageId=1692 or
http://cocoon.zones.apache.org/daisy/documentation/forms/basics/
489.html IIUC (just two examples).
* Why would CMSes opt for SVN as a storage component, given the fact
that SVN for instance doesn't offer query capabilities and has been
designed to manage source code primarily?
* Should this become a requirement, and no-one goes through the pain of
actually writing a usable CMS on top of SVN, isn't this killing
innovation?
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought Open Source Java & XML
stevenn at outerthought.org stevenn at apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: storing documentation in Subversion
Posted by "Roy T. Fielding" <fi...@gbiv.com>.
>> 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?
Not really. The most important fact is that we need tools that
best serve the purpose intended, whether that be issue tracking or
version control or website development.
Secondarily (though also critical to the ASF), we need to track
contributions of intellectual property. That comes in two forms:
initial contributions, like new code or patches, and changes to
existing products in version control. The most important bit of
tracking here is the act of contributing itself -- whether that be
in the form of a JIRA issue creation or a commit. We need to track
both but there is no need to keep everything in subversion. The
point is that what needs to be kept is the record of initial
contribution, which is why a non-authenticated wiki is evil.
We also need change notifications for anything published, since
that is how we achieve oversight.
Wherever possible, we should use the best tools for the job at hand.
But it is important to remember that we cannot use one system to
accept contributions and then throw it away -- we need to have those
logs/versions/notifications intact.
....Roy
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: storing documentation in Subversion
Posted by Trustin Lee <tr...@gmail.com>.
2005/12/20, Ross Gardler <rg...@apache.org>:
> > 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?
If the ASF requirements for traceability is a must, I think we have to
sacrifice individual preferences at least a little bit for the infra team.
Tools such as Trac (http://www.edgewall.com/trac/) is very impressive from
the viewpoint of traceability, but it's not mature yet. We need to find the
gem we can really use for full traceability and integration between various
sources (i.e. wiki, issue tracker, source code repository, mailing list,
...).
> 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?
Storing issues in SVN repository actually sounds similar with storing
mailing list archives in SVN repository. It is too ideal.
What we need is perhaps a CMS which combines:
* site management (support for both production/draft(wiki?))
* issue tracker
* source code repository viewer
* mailing list + forum (like www.nabble.com does)
And if we store all documentation in the CMS, we'll need a tool that fetches
the whole site and includes it into binary distributions.
Trustin
--
what we call human nature is actually human habit
--
http://gleamynode.net/
PGP Key ID: 0x854B996C
Re: storing documentation in Subversion
Posted by Ross Gardler <rg...@apache.org>.
Trustin Lee wrote:
> 2005/12/20, David Crossley <cr...@apache.org>:
...
>>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: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: storing documentation in Subversion
Posted by Trustin Lee <tr...@gmail.com>.
Hello David,
2005/12/20, David Crossley <cr...@apache.org>:
>
> This is a topic that i often hear, not only at new projects.
> People are not sure what needs to be stored in svn and why.
>
> A while ago, Noel raised the issue on the infra@ list. [1]
> Unfortunately not much follow-up. So i wonder if we can
> resolve it here and then document the outcome.
This is an interesting issue, and I think it has to be resolved. Sorry that
there were no many follow-ups.
> 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?
We also store generated documentation in SVN.
> This makes it very easy to restore or replicate
> the websites.
This has been always a good idea, but I guess some projects are not using
this technique for now. For example, the projects which uses Maven as a
build tool look like deploy the site to the filesystem directly. It would
be great if there's some standardized tool many build tools support.
Otherwise, is this issue just for Ant and Maven, or should site publishing
be done manually using 'svn' or 'cvs' command?)
With the advent of new documentation management tools
> (e.g. Lenya, JackRabbit, Daisy) and their potential
> use by ASF projects for their project documentation,
> we are seeing questions about how to enable the
> storage of the sources for documentation.
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. 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? :)
Trustin
--
what we call human nature is actually human habit
--
http://gleamynode.net/