maven-doxia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Vincent Siveton" <>
Subject Re: Preparation of Doxia 1.0-beta-1 release
Date Thu, 11 Dec 2008 12:00:47 GMT
Hi Paul,

2008/12/10 Paul Spencer <>:
> Vincent,
> The project doxia-test-docs should contain the documents and the document
> should be maintained in the projects source repository so they can be
> release by the project, i.e. mvn release...  The version of this project

It is exactly what this new project does. Have a look inside the
project, you could see several Doxia docs (i.e. [1] ) which will be
maintained there.

> should change whenever the source documents change, i.e when you need to
> reload them from the "svn copy", and their is a doxia release.  The tests

Maybe I confused you when I spoke of "svn copy". To be more clear, all
docs are initially copied from their own spaces (see [2]).
The test code doesn't use SCM anymore.

> using doxia-test-docs may need to extract the documents from the
> doxia-test-doc artifact/jar, for which their are maven tools to do the
> unpacking.

It is exactly what the tests do. See [2]

> Keep in mind, one of the reasons for Maven is enable any user at any time
> the ability to successfully rebuild the project.

Sure and I think the build is now reproducible.




> Paul Spencer
> On Dec 10, 2008, at 8:19 PM, Vincent Siveton wrote:
>> Hi Benjamin and Paul,
>> According your comments, I created a new module doxia-test-docs which
>> includes svn copy on several documents. I also updated tests to fetch
>> these changes.
>> Any comments are welcome!
>> Cheers,
>> Vincent
>> 2008/12/8 Benjamin Bentmann <>:
>>> 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

View raw message