Mailing-List: contact doxia-dev-help@maven.apache.org; run by ezmlm
Precedence: bulk
Reply-To: doxia-dev@maven.apache.org
Received-SPF: neutral (nike.apache.org: local policy)
Message-ID: <493D50DF.3040705@udo.edu>
Date: Mon, 08 Dec 2008 17:52:47 +0100
From: Benjamin Bentmann <benjamin.bentmann@udo.edu>
User-Agent: Thunderbird 2.0.0.17 (Windows/20080914)
MIME-Version: 1.0
To: doxia-dev@maven.apache.org
Subject: Re: Preparation of Doxia 1.0-beta-1 release
References: <9ae367340812060657u4e4faa8eqc30fd6a9abbdec65@mail.gmail.com>
	 <493D086E.1060109@apache.org>
 <9ae367340812080417r79da538ap1b8fc5e908c832e1@mail.gmail.com>
In-Reply-To: <9ae367340812080417r79da538ap1b8fc5e908c832e1@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Vincent Siveton wrote:

> The tests are to perform XSD validations under our current
> documentation. Since we add new XSD files in this release, I think
> these tests are useful.

No doubt, tests are useful but I feel we mix two different test targets 
here:

a) correctness of the XSDs
b) correctness of the currently available Maven documentation

IMHO, only point a) should be a concern of Doxia, the rest is just 
outside world. The day we have a validating Doxia under the hood of the 
Site Plugin and it detects errors in our docs, we can simply fix them 
when be try to build the corresponding site, not when building Doxia.

> Instead of svn co, we could link to relative doc path, ie from
> doxia-module-fml using ../../../plugins/maven-ant-plugin/src/site

-1 on hard-coding inter-module or even worse inter-project paths. This 
introduces tight coupling where none should be. Imagine a contributor to 
Doxia who wants to try out patching it would end up checking out Maven 
plugins to test Doxia.

Also, both "svn co" and the relative path to a local checkout make the 
idea of a reproducible build unreachable, as Paul already pointed out.

To realize test target a), it is surely a nice idea to just grab samples 
of existing and presumable good docs and check whether the validator 
doesn't freak out. To do so, how about if we just collect all the doc 
files of interest from the Maven/plugin sites and copy them to a new 
Doxia module (doxia-test-docs or whatever). This module would mimic a 
"svn co" of a locked SVN revision and is also under Doxia control, i.e. 
one could also create artifical input documents to check more complex 
syntax structures that are currently not in use on the Maven sites. The 
other Doxia modules like XDoc etc. could depend on this test module and 
extract the input files from the test class path or from local file 
system after unpacking with the Dependency Plugin. Wouldn't that work?


Benjamin