: But that also makes it important that any committer is given good tools
: to make sure her edits look good. I hope Asciidoc is more standardised
: than Markdown, else your choice of tooling may ultimately decide whether
: your edits look good or bad.
Asciidoc(tor) is much more standardized and rigid the the 1000+ markdown
variants.
Any developer can (and should) rebuild the PDF version of the ref guide to
review their edits in that document. That part of the process is 100%
java and the jars needed are all managed by ant+ivy. AFAIK, for the
forseable future, publishing the ref guide as a PDF will still the
"canonical ref guide".
Much like with java code, your IDE might tell you everything is fine, and
might compile the code & run your tests, but it's up to developers to
verify that the official ant build system (and things like precommit,
documentation-lint) are happy with it. So if your IDE knows about
asciidoctor format, and gives you a preview great -- but the final PDF is
the final PDF. (And once we're integrated into the build, we can write
more & better automated checks that hte docs are "good")
Building the HTML version of the ref guide (such as we might host on
lucene.apache.org) currently can be done fairly easily if a developer has
ruby+jekyll locally installed -- making this work transparently via jruby
proved problematic. By comparison, the pre-reqs and steps needed to do
this are VASTLY easier then trying to build the existing lucene.apache.org
("Apache CMS" based) website content locally on a dev machine -- but even
if devs don't want to do that, it should be pretty easy to set that up on
the apache jenkins slaves for lucene so we can preview those builds --
much like the exsiting web view of CWIKI that.
: Would it be possible to add a JIRA bot that tries to apply the latest
: SOLR-XXXX.patch (like the Hadoop QA bot does, see
: https://issues.apache.org/jira/secure/ViewProfile.jspa?name=hadoopqa
: <https://issues.apache.org/jira/secure/ViewProfile.jspa?name=hadoopqa>)
: and also, if the patch contains .adoc changes, verify and provide a
: preview of those changes right there in JIRA?
That really seems like a much broader & bigger question about how we do
patch review that i'd hate to see sideline this thread. A better way to
look at it that i would consider on topic is this: *IF* we decide, in some
other/future discussion, to add an automated patch review jenkins bot for
Lucene/Solr, then managing the refguide as adoc files living in the same
git repo (on the same branches) as the source code will allow us to have
that (hypothetical) jenkins bot build/review/sanity-check/preview
documentation changes included in patches. If we do *NOT* move forward
with migrating the ref guide to adoc files living in the same git repo (on
the same branches) as the source code -- then those types of verification
checks will be impossible.
-Hoss
http://www.lucidworks.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
