|
»
»
»
« Return to Thread: Preparation of Doxia 1.0-beta-1 release
Re: Preparation of Doxia 1.0-beta-1 release
by Paul Spencer-3
::
Rate this Message:
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 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 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.
Keep in mind, one of the reasons for Maven is enable any user at any
time the ability to successfully rebuild the project.
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 <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
>>
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 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 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.
Keep in mind, one of the reasons for Maven is enable any user at any
time the ability to successfully rebuild the project.
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 <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
>>
« Return to Thread: Preparation of Doxia 1.0-beta-1 release
| Free embeddable forum powered by Nabble | Forum Help |
