Re: Preparation of Doxia 1.0-beta-1 release
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
Hi Paul, 2008/12/10 Paul Spencer [EMAIL PROTECTED]: 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=725511view=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 [EMAIL PROTECTED]: 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 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
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 [EMAIL PROTECTED]: 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, 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 [EMAIL PROTECTED]: 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
On Dec 8, 2008, at 7:37 AM, Vincent Siveton wrote: 2008/12/8 Paul Spencer [EMAIL PROTECTED]: On Dec 8, 2008, at 7:17 AM, Vincent Siveton wrote: 2008/12/8 Lukas Theussl [EMAIL PROTECTED]: 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
2008/12/8 Paul Spencer [EMAIL PROTECTED]: On Dec 8, 2008, at 7:17 AM, Vincent Siveton wrote: 2008/12/8 Lukas Theussl [EMAIL PROTECTED]: 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
On Dec 8, 2008, at 7:17 AM, Vincent Siveton wrote: 2008/12/8 Lukas Theussl [EMAIL PROTECTED]: 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
2008/12/8 Lukas Theussl [EMAIL PROTECTED]: 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
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
