lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Cassandra Targett (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (SOLR-10295) Decide online location for Ref Guide HTML pages
Date Thu, 27 Apr 2017 19:51:04 GMT

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

Cassandra Targett commented on SOLR-10295:
------------------------------------------

A few things from today. The process I followed yesterday for my test of the process stalled
the 6.5.1 release a little bit, and that caused me a bit of time to figure out what was going
wrong there:

* The process I followed likely left out a key step to publish the extpaths.txt from staging
to production.
* The publication of extpaths.txt can't happen until the path you're exempting from sync exists,
and I likely missed that window.

I chatted with INFRA briefly earlier about the problem encountered during the release, and
their suggestion was that we should avoid using extpaths.txt if we can, in case we need to
migrate off the CMS in the future. So I spent some time today on an experiment to try uploading
the Ref Guide via the staging SVN repo (not the web-gui of the CMS). I encountered timeouts
while publishing that to production, and subsequent attempts to make the commit smaller were
unsuccessful, so that made it not worthwhile to recommend as a process. So, to publish the
guide in the CMS, I'm sure will need to use the extpaths.txt method and commit the content
files directly to production.

In the process of playing around with the CMS, I made a permanent directory {{content/solr/guide}}
and included an index.html file there with a bit of placeholder content and a link to my test:
https://lucene.apache.org/solr/guide/.

I have not yet addressed any redirection with index.html or .htaccess so hard-coded the link
from the placeholder landing page to the primary page of the Guide for now.

> 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