[
https://issues.apache.org/jira/browse/SOLR-10295?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15957908#comment-15957908
]
Cassandra Targett commented on SOLR-10295:
------------------------------------------
There are some really good ideas here.
Let's start with what seems we have broad agreement on. Please let me know if I
have misrepresented anything here:
# PDF version remains the "official" released Ref Guide.
** This is a release artifact, and is voted on before release, which will
operate mostly the same as it does today. We vote, it is uploaded to mirrors,
the release is formally announced, etc.
** Currently this still uses Subversion...we can take that up in a separate
issue.
# HTML (online) version is considered a "convenience" version, and it will
exist in multiple versions online
** Online versions correspond to a release, any pending releases, and master
** Doesn't require a vote to publish, can be updated with some degree of
frequency
Then we have an idea that we need to think through a little bit more:
bq. I would fully automate the build and publishing of the various versions of
the HTML ref-guide though a new bot
I like the general outlines of this idea. A few things to mention:
* Currently the HTML build has a few dependencies that must be installed
locally on the build machine (Jekyll is one, which has dependencies on JRuby
and some other stuff). I don't know how open INFRA would be to that being on
their machines, we'd have to check.
* I'm not sure of the efficacy of building for every commit. I believe this is
trying to address the issue of committers being able to see their changes? I
like the idea of putting a comment in the related JIRA issue to the newly built
version of the guide, but wonder how useful it will be in practice (and thus if
it's worth building). 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. One thing that might mitigate that is publishing only pages which have
changed - our build scripts don't handle this at all today, we'd have to
rethink that some.
* We can add to the top navigation bar some text that changes depending on the
version being reviewed. There are multiple ways we can do this - if/then
statements in the Liquid template, Javascript, etc.
While I like this idea and would like to implement it (or some variant of it),
I wonder if it might be more effective in order to make progress for us to
split this specific idea into a separate issue to tackle it. We can have an
easy publication process today - someone builds it on their local machine and
puts it somewhere. It's the "where" part of that somewhere that we need to get
resolved. If we split this off, we can work on it in conjunction with the other
issues that remain unresolved, such as the actual work of the conversion, but
still be able to cut over to the new approach and add automation shortly
thereafter.
Anyone have an alternative to my idea of using the CMS to host the docs the
same way the Javadocs are hosted? (Note, we need to use an apache.org server or
the comments will not appear...We could check with INFRA about that, but it
seems it should be apache.org hosted so it can really be considered something
quasi-official.)
> 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: [email protected]
For additional commands, e-mail: [email protected]
