lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jan Høydahl (JIRA) <j...@apache.org>
Subject [jira] [Commented] (SOLR-10295) Decide online location for Ref Guide HTML pages
Date Fri, 07 Apr 2017 12:05:41 GMT

    [ https://issues.apache.org/jira/browse/SOLR-10295?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15960664#comment-15960664
] 

Jan Høydahl commented on SOLR-10295:
------------------------------------

The GitPubSub sounds very attractive, if that means we can have a lightweight job in Jenkins
that only builds the refGuide on each commit.

bq. I also wonder about publishing a new version for every change - I wonder if that will
make the docs in a constant state of flux? We know from experience that users will more likely
use the online version, so we want some degree of stability there, even if it's not really
the "official" version.

Most commits would be {{master}} or {{branch_6x}} and trigger a refGuide build of unreleased
next-ver docs, no problem with flux there.
Any asciidoc commits on release-branches (e.g. branch_6_5) would be few and minor, so should
not create much flux either.
The default version of the refGude hosted on http://lucene.apache.org/solr/guide/ should be
the one for latest stable, and then users can choose to view for earlier branches as well
as the unstable.

I think we should attempt to have all versions of the guide in the same place. Alternatively,
I guess it would be fine if the master/branch_6x versions were either linked or redirected
from the CMS /solr/guide to the location in Jenkins...

> Decide online location for Ref Guide HTML pages
> -----------------------------------------------
>
>                 Key: SOLR-10295
>                 URL: https://issues.apache.org/jira/browse/SOLR-10295
>             Project: Solr
>          Issue Type: Sub-task
>      Security Level: Public(Default Security Level. Issues are Public) 
>          Components: documentation
>            Reporter: Cassandra Targett
>
> One of the biggest decisions we need to make is where to put the new Solr Ref Guide.
Confluence at least had the whole web-hosting bits figured out; we have to figure that out
on our own.
> An obvious (maybe only to me) choice is to integrate the Ref Guide with the Solr Website.
However, due to the size of the Solr Ref Guide (nearly 200 pages), I believe trying to publish
it solely with existing CMS tools will create problems similar to those described in the Lucene
ReleaseTodo when it comes to publishing the Lucene/Solr javadocs (see https://wiki.apache.org/lucene-java/ReleaseTodo#Website_.2B-.3D_javadocs).
> A solution exists already, and it's what is done for the javadocs. From the above link:
> {quote}
> The solution: skip committing javadocs to the source tree, then staging, then publishing,
and instead commit javadocs directly to the production tree. Ordinarily this would be problematic,
because the CMS wants to keep the production tree in sync with the staging tree, so anything
it finds in the production tree that's not in the staging tree gets nuked. However, the CMS
has a built-in mechanism to allow exceptions to the keep-production-in-sync-with-staging rule:
extpaths.txt.
> {quote}
> This solution (for those who don't know already) is to provide a static text file (extpaths.txt)
that includes the javadoc paths that should be presented in production, but which won't exist
in CMS staging environments. This way, we can publish HTML files directly to production and
they will be preserved when the staging-production trees are synced.
> The rest of the process would be quite similar to what is documented in the ReleaseTodo
in sections following the link above - use SVN to update the CMS production site and update
extpaths.txt properly. We'd do this in the {{solr}} section of the CMS obviously, and not
the {{lucene}} section.
> A drawback to this approach is that we won't have a staging area to view the Guide before
publication. Files would be generated and go to production directly. We may want to put a
process in place to give some additional confidence that things look right first (someone's
people.apache.org directory? a pre-pub validation script that tests...something...?), and
agree on what we'd be voting on when a vote to release comes up. However, the CMS is pretty
much the only option that I can think of...other ideas are welcome if they might work.
> We also need to agree on URL paths that make sense, considering we'll have a new "site"
for each major release - something like {{http://lucene.apache.org/solr/ref-guide/6_1}} might
work? Other thoughts are welcome on this point also.



--
This message was sent by Atlassian JIRA
(v6.3.15#6346)

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: dev-help@lucene.apache.org


Mime
View raw message