[jira] [Comment Edited] (SOLR-10295) Decide online location for Ref Guide HTML pages

["Shawn Heisey (JIRA)" <ji...@apache.org>]

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

Shawn Heisey edited comment on SOLR-10295 at 3/18/17 4:05 PM:
--------------------------------------------------------------

bq. Define only the PDF as the official guide release. The versioned online HTML-format guides are convenience versions, not officially signed etc. That gives us great freedom for how and where to place HTML versions, also without need for formal voting.

I like this plan.  Official releases are in a format that's resistant to change, contained in a single file with an easily verified signature.  If we retroactively discover that there's a big enough problem with a versioned PDF that we need to fix it, we can vote on a replacement release, which I think would be how X.Y.1 releases of the ref guide might become a reality.  For bugfix binary releases, we generally avoid making changes that would require a documentation update.

Ref guide releases (especially those beyond X.Y.0) could be completely independent of similarly numbered reference guide releases.  Separate releases is likely to require separate tags that actually contain something like "refguide" in the name, but I believe git makes those really cheap.  Of course we would TRY to only release X.Y.0 reference guides, from the exact same tag as the binary.  Always synchronizing point releases with ref guide releases of the same version number would open the door to including more substantial changes in a point release, which I think we probably don't want.

If online HTML versions of the guide are NOT official release product, I think Jan's right.  We should be able to rebuild them as necessary, by any mechanism, without a vote.



was (Author: elyograg):
bq. Define only the PDF as the official guide release. The versioned online HTML-format guides are convenience versions, not officially signed etc. That gives us great freedom for how and where to place HTML versions, also without need for formal voting.

I like this plan.  Official releases are in a format that's resistant to change, contained in a single file that can be accompanied by a signature.  If we retroactively discover that there's a big enough problem with a versioned PDF that we need to fix it, we can vote on a replacement release, which I think would be how X.Y.1 releases of the ref guide might become a reality.  For bugfix binary releases, we generally avoid making changes that would require a documentation update.

Ref guide releases (especially those beyond X.Y.0) could be completely independent of similarly numbered reference guide releases.  Separate releases is likely to require separate tags that actually contain something like "refguide" in the name, but I believe git makes those really cheap.  Of course we would TRY to only release X.Y.0 reference guides, from the exact same tag as the binary.  Always synchronizing point releases with ref guide releases of the same version number would open the door to including more substantial changes in a point release, which I think we probably don't want.

If online HTML versions of the guide are NOT official release product, I think Jan's right.  We should be able to rebuild them as necessary, by any mechanism, without a vote.


> 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