Preparation of Doxia 1.0-beta-1 release

[Vincent Siveton <vi...@gmail.com>]

Hi guys,

IMHO Doxia 1.0-beta-1 could be release soon, ideally for xmas!
So, do you think we are missing issues?
Any other comments?

Cheers,

Vincent

Re: Preparation of Doxia 1.0-beta-1 release

[Paul Spencer <pa...@apache.org>]

On Dec 12, 2008, at 10:59 AM, Dennis Lundberg wrote:

> Hi Vincent
>
> Can we have a quit poll about version numbering. We have had  
> discussions
> about this in the past and I'd like to come to a conclusion now that  
> the
> release is getting closer.
>
> The proposal that was made earlier was this:
>
> 1. Create an Doxia 1.0 release from the current doxia-1.0-alpha-x  
> branch
>
> 2. Release the current trunk as version 1.1 (currently labeled as
> 1.0-beta-1 in JIRA)
>
> One reason for this change would be to get out of the alpha/beta mess.
>

+1 If both 1.0-alpha-x and 1.0-beta are viable and stable on their own.


> It would also align version numbers nicely with Maven and the Site  
> Plugin.
>
> We would the have two parallel tracks:
>
> Track one: Maven 2.0.x + Doxia 1.0.x + Site Plugin 2.0.x
>
> Track two: Maven 2.1.x + Doxia 1.1.x + Site Plugin 2.1.x
>
> This also ties in with the Doxia Release Plan [1]
>

In general I am not a fan of aligning version number with product you  
do not control.  In part because you loose control of the version  
numbers.  That said, I do not have a problem with aligning a branch to  
a version of another product, like you describe above.

> I will have some time off from work during the holidays and will be  
> able
> to help.
>
>
> WDYT?
>
>
> [1] http://docs.codehaus.org/display/MAVEN/Doxia+Release+Plan
>
>
<snip>
>
> -- 
> Dennis Lundberg


Paul Spencer

Re: Preparation of Doxia 1.0-beta-1 release

[Dennis Lundberg <de...@apache.org>]

Hi Vincent

Can we have a quit poll about version numbering. We have had discussions
about this in the past and I'd like to come to a conclusion now that the
release is getting closer.

The proposal that was made earlier was this:

1. Create an Doxia 1.0 release from the current doxia-1.0-alpha-x branch

2. Release the current trunk as version 1.1 (currently labeled as
1.0-beta-1 in JIRA)

One reason for this change would be to get out of the alpha/beta mess.

It would also align version numbers nicely with Maven and the Site Plugin.

We would the have two parallel tracks:

Track one: Maven 2.0.x + Doxia 1.0.x + Site Plugin 2.0.x

Track two: Maven 2.1.x + Doxia 1.1.x + Site Plugin 2.1.x

This also ties in with the Doxia Release Plan [1]

I will have some time off from work during the holidays and will be able
to help.


WDYT?


[1] http://docs.codehaus.org/display/MAVEN/Doxia+Release+Plan


Vincent Siveton wrote:
> Hi guys,
> 
> IMHO Doxia 1.0-beta-1 could be release soon, ideally for xmas!
> So, do you think we are missing issues?
> Any other comments?
> 
> Cheers,
> 
> Vincent
> 


-- 
Dennis Lundberg

Re: Preparation of Doxia 1.0-beta-1 release

[Benjamin Bentmann <be...@udo.edu>]

Vincent Siveton wrote:

> Any comments are welcome!

Building the whole Doxia trunk takes only ~1 min for me, fine work IMHO 
Vincent :-) !


Benjamin

Re: Preparation of Doxia 1.0-beta-1 release

[Vincent Siveton <vi...@gmail.com>]

Hi Paul,

2008/12/10 Paul Spencer <pa...@apache.org>:
> 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.

Cheers,

Vincent

[1] https://svn.apache.org/repos/asf/maven/doxia/doxia/trunk/doxia-test-docs/src/main/resources/maven-ant-plugin/fml/
[2] http://svn.apache.org/viewvc?rev=725511&view=rev
[3] https://svn.apache.org/repos/asf/maven/doxia/doxia/trunk/doxia-core/src/test/java/org/apache/maven/doxia/xsd/AbstractXmlValidatorTest.java

>
> 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 <be...@udo.edu>:
>>>
>>> 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
>>>
>
>

Re: Preparation of Doxia 1.0-beta-1 release

[Paul Spencer <pa...@apache.org>]

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 <be...@udo.edu>:
>> 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
>>

Re: Preparation of Doxia 1.0-beta-1 release

[Vincent Siveton <vi...@gmail.com>]

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 <be...@udo.edu>:
> 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
>

Re: Preparation of Doxia 1.0-beta-1 release

[Benjamin Bentmann <be...@udo.edu>]

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

Re: Preparation of Doxia 1.0-beta-1 release

[Paul Spencer <pa...@apache.org>]

On Dec 8, 2008, at 7:37 AM, Vincent Siveton wrote:

> 2008/12/8 Paul Spencer <pa...@apache.org>:
>>
>> On Dec 8, 2008, at 7:17 AM, Vincent Siveton wrote:
>>
>>> 2008/12/8 Lukas Theussl <lt...@apache.org>:
>>>>
>>>> I just noticed that the fml module now takes ~5min to build  
>>>> instead of a
>>>> few
>>>
>>> Same for xdoc module.
>>>
>>>> secs for all other modules. There are some svn checkouts during  
>>>> testing,
>>>> are
>>>> those necessary? Does it mean you can't build doxia off-line?
>>>
>>> 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.
>>>
>>> About off-line build, we need to be sure that latest Maven doc is
>>> again valid (and BTW doxia needs external dependencies)
>>> Instead of svn co, we could link to relative doc path, ie from
>>> doxia-module-fml using ../../../plugins/maven-ant-plugin/src/site
>>> This approach has pros/cons like svn co.
>>>
>>> WDYT?
>>
>> Why are you not using a dependency? A "svn co" does not insure a
>> reproduceable build.
>
> Using a separate dependency or a given test folder insures that the
> documentation is valid, right.
> But how to be sure that the *latest* doc is still valid under our xsd?
> Is it a reasonable test case?

I am not sure the best way to insure the documentation is in sync.   
The "snippet" macro from a test case is one tool.  The test cases can  
verify the XSD "matches" the doc.  I say "matches" because it does not  
verify the documentation is in sync with the test case.

>
>
> Vincent
>

Paul Spencer

Re: Preparation of Doxia 1.0-beta-1 release

[Vincent Siveton <vi...@gmail.com>]

2008/12/8 Paul Spencer <pa...@apache.org>:
>
> On Dec 8, 2008, at 7:17 AM, Vincent Siveton wrote:
>
>> 2008/12/8 Lukas Theussl <lt...@apache.org>:
>>>
>>> I just noticed that the fml module now takes ~5min to build instead of a
>>> few
>>
>> Same for xdoc module.
>>
>>> secs for all other modules. There are some svn checkouts during testing,
>>> are
>>> those necessary? Does it mean you can't build doxia off-line?
>>
>> 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.
>>
>> About off-line build, we need to be sure that latest Maven doc is
>> again valid (and BTW doxia needs external dependencies)
>> Instead of svn co, we could link to relative doc path, ie from
>> doxia-module-fml using ../../../plugins/maven-ant-plugin/src/site
>> This approach has pros/cons like svn co.
>>
>> WDYT?
>
> Why are you not using a dependency? A "svn co" does not insure a
> reproduceable build.

Using a separate dependency or a given test folder insures that the
documentation is valid, right.
But how to be sure that the *latest* doc is still valid under our xsd?
Is it a reasonable test case?

Vincent

> Paul Spencer
>
>

Re: Preparation of Doxia 1.0-beta-1 release

[Paul Spencer <pa...@apache.org>]

On Dec 8, 2008, at 7:17 AM, Vincent Siveton wrote:

> 2008/12/8 Lukas Theussl <lt...@apache.org>:
>>
>> I just noticed that the fml module now takes ~5min to build instead  
>> of a few
>
> Same for xdoc module.
>
>> secs for all other modules. There are some svn checkouts during  
>> testing, are
>> those necessary? Does it mean you can't build doxia off-line?
>
> 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.
>
> About off-line build, we need to be sure that latest Maven doc is
> again valid (and BTW doxia needs external dependencies)
> Instead of svn co, we could link to relative doc path, ie from
> doxia-module-fml using ../../../plugins/maven-ant-plugin/src/site
> This approach has pros/cons like svn co.
>
> WDYT?

Why are you not using a dependency? A "svn co" does not insure a  
reproduceable build.

Paul Spencer

Re: Preparation of Doxia 1.0-beta-1 release

[Vincent Siveton <vi...@gmail.com>]

2008/12/8 Lukas Theussl <lt...@apache.org>:
>
> I just noticed that the fml module now takes ~5min to build instead of a few

Same for xdoc module.

> secs for all other modules. There are some svn checkouts during testing, are
> those necessary? Does it mean you can't build doxia off-line?

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.

About off-line build, we need to be sure that latest Maven doc is
again valid (and BTW doxia needs external dependencies)
Instead of svn co, we could link to relative doc path, ie from
doxia-module-fml using ../../../plugins/maven-ant-plugin/src/site
This approach has pros/cons like svn co.

WDYT?

Vincent

>
> -Lukas
>
>
> Vincent Siveton wrote:
>>
>> Hi guys,
>>
>> IMHO Doxia 1.0-beta-1 could be release soon, ideally for xmas!
>> So, do you think we are missing issues?
>> Any other comments?
>>
>> Cheers,
>>
>> Vincent
>>
>

Re: Preparation of Doxia 1.0-beta-1 release

[Lukas Theussl <lt...@apache.org>]

I just noticed that the fml module now takes ~5min to build instead of a few secs 
for all other modules. There are some svn checkouts during testing, are those 
necessary? Does it mean you can't build doxia off-line?

-Lukas


Vincent Siveton wrote:
> Hi guys,
> 
> IMHO Doxia 1.0-beta-1 could be release soon, ideally for xmas!
> So, do you think we are missing issues?
> Any other comments?
> 
> Cheers,
> 
> Vincent
>