[
https://issues.apache.org/jira/browse/SOLR-10295?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15930541#comment-15930541
]
Cassandra Targett commented on SOLR-10295:
------------------------------------------
We should define "release" probably.
Today we have an online version which is always marked as for the next release.
This is because we have to be able to edit content somewhere - there is no
realistic offline editing in Confluence - and we don't have the ability to
version it online either. So we have one live document that needs to serve as
the staging area for updates to the Guide for an upcoming version. Because of
this, the Official Ref Guide is the PDF version because it's the only thing we
can "bless" as being accurate for a particular Solr version. The PDF is the
release.
This whole scenario changes now. We have the ability to edit the content
without it impacting what users see online. We can do this in branches or on
master or wherever. What users see online now has to be specifically built &
published because we can edit content all day without it changing what users
see anywhere. In my mind, I now consider the online version a release. There
will be two "artifacts", as it were, instead of just one - an HTML format and a
PDF format (and maybe later an EPUB version or whatever other format people
would like to see).
I don't think you were misunderstanding the issue, there are multiple questions
here:
* Where does the online version live?
* What are the steps between running {{ant build}} and having a live site?
* What is the approval process for releasing?
* What do we do if there are changes needed between releases?
* If we re-publish, do we also re-publish the PDF (and other formats)?
I didn't list all these in my original description, but they are all related,
so it makes sense to try to resolve them here.
> 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-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
