Re: Site-book broken in master
Thanks Otto. Moving this discussion to a DISCUSS thread and closing out the PR now. On Thu, Dec 20, 2018 at 11:00 AM Otto Fowler wrote: > https://github.com/oasp/asciidoc-link-checker > > > On December 20, 2018 at 12:59:39, Otto Fowler (ottobackwa...@gmail.com) > wrote: > > +1 for merging a fix. > > > > On December 20, 2018 at 12:43:57, Michael Miklavcic ( > michael.miklav...@gmail.com) wrote: > > Thanks for the feedback Otto. I'm not too familiar with our infrastructure > afa impact of switching to ascii doc, but I think it's worth considering if > it allows us to have a consistent rendering markdown that's easy to use. > Automated link testing is a good idea. I wonder if Cypress could do that > well, or if we should just write our own link tester that spins up embedded > Jetty, or other option. > > *Anyone opposed to me merging this PR in sooner than the 24 hour period?* > This is a broken master as far as I'm concerned, despite what Travis says. > > In a separate PR, I'd also like to add a simple mvn clean site run to our > Travis builds, which should catch the bigger issues. > > On Wed, Dec 19, 2018 at 8:51 PM Otto Fowler > wrote: > >> Maybe we should consider ascii doc, it shows in github, and can generate >> multiple formats. >> >> >> >> On December 19, 2018 at 22:49:26, Otto Fowler (ottobackwa...@gmail.com) >> wrote: >> >> What would help is an automated test the tests all the links as well. >> >> >> >> On December 19, 2018 at 19:55:03, Michael Miklavcic ( >> michael.miklav...@gmail.com) wrote: >> >> I'd also like to submit a call for suggestions for making this process >> simpler. I think we've made some excellent progress towards getting an >> html-generated version of our documentation, but it's also proving to be >> somewhat error-prone. Github and Doxia have different expectations as to >> formatting, and most devs are generally looking at Github rendering only >> because we get that for free as part of the Github PR lifecycle. In >> addition, images are managed independently. Missing a reference, getting >> the relative path wrong, or getting the rewrite rules incorrect will >> result >> in a bad time. I've seen at least a few PR's in recent memory unwittingly >> fall into this trap. >> >> On Wed, Dec 19, 2018 at 5:47 PM Michael Miklavcic < >> michael.miklav...@gmail.com> wrote: >> >> > Fix is out in this PR: https://github.com/apache/metron/pull/1309 >> > Jira: https://issues.apache.org/jira/browse/METRON-1950 >> > >> > It ended up being a bit bigger than I hoped because we had some >> remaining >> > incompatibilities between our Github markdown and the Doxia-expected >> > formatting. This caused a cascade of inconsistent results for anyone >> > attempting to generate a page that works in both Github markdown and >> Doxia. >> > The latest fixes here should address all of this in the parsers >> > documentation. I suspect we may have other markdown pages out there that >> > will have similar issues, so this PR/Jira/notice should serve as a >> recipe >> > for remedying them in the future. >> > >> > Best, >> > Mike >> > >> > >> > On Wed, Dec 19, 2018 at 3:46 PM Michael Miklavcic < >> > michael.miklav...@gmail.com> wrote: >> > >> >> FYI, site-book is currently broken in master. I think I've found the >> >> source of the issue and will be issuing a fix shortly. >> >> >> >> Best, >> >> Mike >> >> >> > >> >>
Re: Site-book broken in master
https://github.com/oasp/asciidoc-link-checker On December 20, 2018 at 12:59:39, Otto Fowler (ottobackwa...@gmail.com) wrote: +1 for merging a fix. On December 20, 2018 at 12:43:57, Michael Miklavcic ( michael.miklav...@gmail.com) wrote: Thanks for the feedback Otto. I'm not too familiar with our infrastructure afa impact of switching to ascii doc, but I think it's worth considering if it allows us to have a consistent rendering markdown that's easy to use. Automated link testing is a good idea. I wonder if Cypress could do that well, or if we should just write our own link tester that spins up embedded Jetty, or other option. *Anyone opposed to me merging this PR in sooner than the 24 hour period?* This is a broken master as far as I'm concerned, despite what Travis says. In a separate PR, I'd also like to add a simple mvn clean site run to our Travis builds, which should catch the bigger issues. On Wed, Dec 19, 2018 at 8:51 PM Otto Fowler wrote: > Maybe we should consider ascii doc, it shows in github, and can generate > multiple formats. > > > > On December 19, 2018 at 22:49:26, Otto Fowler (ottobackwa...@gmail.com) > wrote: > > What would help is an automated test the tests all the links as well. > > > > On December 19, 2018 at 19:55:03, Michael Miklavcic ( > michael.miklav...@gmail.com) wrote: > > I'd also like to submit a call for suggestions for making this process > simpler. I think we've made some excellent progress towards getting an > html-generated version of our documentation, but it's also proving to be > somewhat error-prone. Github and Doxia have different expectations as to > formatting, and most devs are generally looking at Github rendering only > because we get that for free as part of the Github PR lifecycle. In > addition, images are managed independently. Missing a reference, getting > the relative path wrong, or getting the rewrite rules incorrect will result > in a bad time. I've seen at least a few PR's in recent memory unwittingly > fall into this trap. > > On Wed, Dec 19, 2018 at 5:47 PM Michael Miklavcic < > michael.miklav...@gmail.com> wrote: > > > Fix is out in this PR: https://github.com/apache/metron/pull/1309 > > Jira: https://issues.apache.org/jira/browse/METRON-1950 > > > > It ended up being a bit bigger than I hoped because we had some remaining > > incompatibilities between our Github markdown and the Doxia-expected > > formatting. This caused a cascade of inconsistent results for anyone > > attempting to generate a page that works in both Github markdown and > Doxia. > > The latest fixes here should address all of this in the parsers > > documentation. I suspect we may have other markdown pages out there that > > will have similar issues, so this PR/Jira/notice should serve as a recipe > > for remedying them in the future. > > > > Best, > > Mike > > > > > > On Wed, Dec 19, 2018 at 3:46 PM Michael Miklavcic < > > michael.miklav...@gmail.com> wrote: > > > >> FYI, site-book is currently broken in master. I think I've found the > >> source of the issue and will be issuing a fix shortly. > >> > >> Best, > >> Mike > >> > > > >
Re: Site-book broken in master
+1 for merging a fix. On December 20, 2018 at 12:43:57, Michael Miklavcic ( michael.miklav...@gmail.com) wrote: Thanks for the feedback Otto. I'm not too familiar with our infrastructure afa impact of switching to ascii doc, but I think it's worth considering if it allows us to have a consistent rendering markdown that's easy to use. Automated link testing is a good idea. I wonder if Cypress could do that well, or if we should just write our own link tester that spins up embedded Jetty, or other option. *Anyone opposed to me merging this PR in sooner than the 24 hour period?* This is a broken master as far as I'm concerned, despite what Travis says. In a separate PR, I'd also like to add a simple mvn clean site run to our Travis builds, which should catch the bigger issues. On Wed, Dec 19, 2018 at 8:51 PM Otto Fowler wrote: > Maybe we should consider ascii doc, it shows in github, and can generate > multiple formats. > > > > On December 19, 2018 at 22:49:26, Otto Fowler (ottobackwa...@gmail.com) > wrote: > > What would help is an automated test the tests all the links as well. > > > > On December 19, 2018 at 19:55:03, Michael Miklavcic ( > michael.miklav...@gmail.com) wrote: > > I'd also like to submit a call for suggestions for making this process > simpler. I think we've made some excellent progress towards getting an > html-generated version of our documentation, but it's also proving to be > somewhat error-prone. Github and Doxia have different expectations as to > formatting, and most devs are generally looking at Github rendering only > because we get that for free as part of the Github PR lifecycle. In > addition, images are managed independently. Missing a reference, getting > the relative path wrong, or getting the rewrite rules incorrect will result > in a bad time. I've seen at least a few PR's in recent memory unwittingly > fall into this trap. > > On Wed, Dec 19, 2018 at 5:47 PM Michael Miklavcic < > michael.miklav...@gmail.com> wrote: > > > Fix is out in this PR: https://github.com/apache/metron/pull/1309 > > Jira: https://issues.apache.org/jira/browse/METRON-1950 > > > > It ended up being a bit bigger than I hoped because we had some remaining > > incompatibilities between our Github markdown and the Doxia-expected > > formatting. This caused a cascade of inconsistent results for anyone > > attempting to generate a page that works in both Github markdown and > Doxia. > > The latest fixes here should address all of this in the parsers > > documentation. I suspect we may have other markdown pages out there that > > will have similar issues, so this PR/Jira/notice should serve as a recipe > > for remedying them in the future. > > > > Best, > > Mike > > > > > > On Wed, Dec 19, 2018 at 3:46 PM Michael Miklavcic < > > michael.miklav...@gmail.com> wrote: > > > >> FYI, site-book is currently broken in master. I think I've found the > >> source of the issue and will be issuing a fix shortly. > >> > >> Best, > >> Mike > >> > > > >
Re: Site-book broken in master
Thanks for the feedback Otto. I'm not too familiar with our infrastructure afa impact of switching to ascii doc, but I think it's worth considering if it allows us to have a consistent rendering markdown that's easy to use. Automated link testing is a good idea. I wonder if Cypress could do that well, or if we should just write our own link tester that spins up embedded Jetty, or other option. *Anyone opposed to me merging this PR in sooner than the 24 hour period?* This is a broken master as far as I'm concerned, despite what Travis says. In a separate PR, I'd also like to add a simple mvn clean site run to our Travis builds, which should catch the bigger issues. On Wed, Dec 19, 2018 at 8:51 PM Otto Fowler wrote: > Maybe we should consider ascii doc, it shows in github, and can generate > multiple formats. > > > > On December 19, 2018 at 22:49:26, Otto Fowler (ottobackwa...@gmail.com) > wrote: > > What would help is an automated test the tests all the links as well. > > > > On December 19, 2018 at 19:55:03, Michael Miklavcic ( > michael.miklav...@gmail.com) wrote: > > I'd also like to submit a call for suggestions for making this process > simpler. I think we've made some excellent progress towards getting an > html-generated version of our documentation, but it's also proving to be > somewhat error-prone. Github and Doxia have different expectations as to > formatting, and most devs are generally looking at Github rendering only > because we get that for free as part of the Github PR lifecycle. In > addition, images are managed independently. Missing a reference, getting > the relative path wrong, or getting the rewrite rules incorrect will result > in a bad time. I've seen at least a few PR's in recent memory unwittingly > fall into this trap. > > On Wed, Dec 19, 2018 at 5:47 PM Michael Miklavcic < > michael.miklav...@gmail.com> wrote: > > > Fix is out in this PR: https://github.com/apache/metron/pull/1309 > > Jira: https://issues.apache.org/jira/browse/METRON-1950 > > > > It ended up being a bit bigger than I hoped because we had some remaining > > incompatibilities between our Github markdown and the Doxia-expected > > formatting. This caused a cascade of inconsistent results for anyone > > attempting to generate a page that works in both Github markdown and > Doxia. > > The latest fixes here should address all of this in the parsers > > documentation. I suspect we may have other markdown pages out there that > > will have similar issues, so this PR/Jira/notice should serve as a recipe > > for remedying them in the future. > > > > Best, > > Mike > > > > > > On Wed, Dec 19, 2018 at 3:46 PM Michael Miklavcic < > > michael.miklav...@gmail.com> wrote: > > > >> FYI, site-book is currently broken in master. I think I've found the > >> source of the issue and will be issuing a fix shortly. > >> > >> Best, > >> Mike > >> > > > >
Re: Site-book broken in master
What would help is an automated test the tests all the links as well. On December 19, 2018 at 19:55:03, Michael Miklavcic ( michael.miklav...@gmail.com) wrote: I'd also like to submit a call for suggestions for making this process simpler. I think we've made some excellent progress towards getting an html-generated version of our documentation, but it's also proving to be somewhat error-prone. Github and Doxia have different expectations as to formatting, and most devs are generally looking at Github rendering only because we get that for free as part of the Github PR lifecycle. In addition, images are managed independently. Missing a reference, getting the relative path wrong, or getting the rewrite rules incorrect will result in a bad time. I've seen at least a few PR's in recent memory unwittingly fall into this trap. On Wed, Dec 19, 2018 at 5:47 PM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > Fix is out in this PR: https://github.com/apache/metron/pull/1309 > Jira: https://issues.apache.org/jira/browse/METRON-1950 > > It ended up being a bit bigger than I hoped because we had some remaining > incompatibilities between our Github markdown and the Doxia-expected > formatting. This caused a cascade of inconsistent results for anyone > attempting to generate a page that works in both Github markdown and Doxia. > The latest fixes here should address all of this in the parsers > documentation. I suspect we may have other markdown pages out there that > will have similar issues, so this PR/Jira/notice should serve as a recipe > for remedying them in the future. > > Best, > Mike > > > On Wed, Dec 19, 2018 at 3:46 PM Michael Miklavcic < > michael.miklav...@gmail.com> wrote: > >> FYI, site-book is currently broken in master. I think I've found the >> source of the issue and will be issuing a fix shortly. >> >> Best, >> Mike >> >
Re: Site-book broken in master
Maybe we should consider ascii doc, it shows in github, and can generate multiple formats. On December 19, 2018 at 22:49:26, Otto Fowler (ottobackwa...@gmail.com) wrote: What would help is an automated test the tests all the links as well. On December 19, 2018 at 19:55:03, Michael Miklavcic ( michael.miklav...@gmail.com) wrote: I'd also like to submit a call for suggestions for making this process simpler. I think we've made some excellent progress towards getting an html-generated version of our documentation, but it's also proving to be somewhat error-prone. Github and Doxia have different expectations as to formatting, and most devs are generally looking at Github rendering only because we get that for free as part of the Github PR lifecycle. In addition, images are managed independently. Missing a reference, getting the relative path wrong, or getting the rewrite rules incorrect will result in a bad time. I've seen at least a few PR's in recent memory unwittingly fall into this trap. On Wed, Dec 19, 2018 at 5:47 PM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > Fix is out in this PR: https://github.com/apache/metron/pull/1309 > Jira: https://issues.apache.org/jira/browse/METRON-1950 > > It ended up being a bit bigger than I hoped because we had some remaining > incompatibilities between our Github markdown and the Doxia-expected > formatting. This caused a cascade of inconsistent results for anyone > attempting to generate a page that works in both Github markdown and Doxia. > The latest fixes here should address all of this in the parsers > documentation. I suspect we may have other markdown pages out there that > will have similar issues, so this PR/Jira/notice should serve as a recipe > for remedying them in the future. > > Best, > Mike > > > On Wed, Dec 19, 2018 at 3:46 PM Michael Miklavcic < > michael.miklav...@gmail.com> wrote: > >> FYI, site-book is currently broken in master. I think I've found the >> source of the issue and will be issuing a fix shortly. >> >> Best, >> Mike >> >
Re: Site-book broken in master
I'd also like to submit a call for suggestions for making this process simpler. I think we've made some excellent progress towards getting an html-generated version of our documentation, but it's also proving to be somewhat error-prone. Github and Doxia have different expectations as to formatting, and most devs are generally looking at Github rendering only because we get that for free as part of the Github PR lifecycle. In addition, images are managed independently. Missing a reference, getting the relative path wrong, or getting the rewrite rules incorrect will result in a bad time. I've seen at least a few PR's in recent memory unwittingly fall into this trap. On Wed, Dec 19, 2018 at 5:47 PM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > Fix is out in this PR: https://github.com/apache/metron/pull/1309 > Jira: https://issues.apache.org/jira/browse/METRON-1950 > > It ended up being a bit bigger than I hoped because we had some remaining > incompatibilities between our Github markdown and the Doxia-expected > formatting. This caused a cascade of inconsistent results for anyone > attempting to generate a page that works in both Github markdown and Doxia. > The latest fixes here should address all of this in the parsers > documentation. I suspect we may have other markdown pages out there that > will have similar issues, so this PR/Jira/notice should serve as a recipe > for remedying them in the future. > > Best, > Mike > > > On Wed, Dec 19, 2018 at 3:46 PM Michael Miklavcic < > michael.miklav...@gmail.com> wrote: > >> FYI, site-book is currently broken in master. I think I've found the >> source of the issue and will be issuing a fix shortly. >> >> Best, >> Mike >> >
Re: Site-book broken in master
Fix is out in this PR: https://github.com/apache/metron/pull/1309 Jira: https://issues.apache.org/jira/browse/METRON-1950 It ended up being a bit bigger than I hoped because we had some remaining incompatibilities between our Github markdown and the Doxia-expected formatting. This caused a cascade of inconsistent results for anyone attempting to generate a page that works in both Github markdown and Doxia. The latest fixes here should address all of this in the parsers documentation. I suspect we may have other markdown pages out there that will have similar issues, so this PR/Jira/notice should serve as a recipe for remedying them in the future. Best, Mike On Wed, Dec 19, 2018 at 3:46 PM Michael Miklavcic < michael.miklav...@gmail.com> wrote: > FYI, site-book is currently broken in master. I think I've found the > source of the issue and will be issuing a fix shortly. > > Best, > Mike >
Site-book broken in master
FYI, site-book is currently broken in master. I think I've found the source of the issue and will be issuing a fix shortly. Best, Mike
