[
https://issues.apache.org/jira/browse/SOLR-10295?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15930934#comment-15930934
]
Jan Høydahl commented on SOLR-10295:
------------------------------------
Here's my dream scenario
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 would fully automate the build and publishing of the various versions of the
HTML ref-guide though a new bot. The bot would watch git commits, build the
HTML guide and publish it.
I think {{http://lucene.apache.org/solr/guide/}} would be a great landing page
for the guide. It would be a page highlighting the latest official released
guide, as well as linking to historic versions and also, less prominently,
unreleased versions, such as master, branch_6x, branch_6_4 etc. This landing
page could even be an SPA with auto generated links based on info we already
have in [DOAP|https://projects.apache.org/json/projects/lucene-core.json] and
git. So we would have
{noformat}
http://lucene.apache.org/solr/guide/ (main landing page)
http://lucene.apache.org/solr/guide/6_5/ (built from branch_6_5, this way we
can release bugfixes simply by committing to the branch)
http://lucene.apache.org/solr/guide/branch_6x/ (build from branch_6x, next
feature version to be released)
http://lucene.apache.org/solr/guide/master/ (build from master, next major
version to be released)
http://lucene.apache.org/solr/guide/7_0/ (the permlink for Solr7 once it is
released)
...
{noformat}
So the bot (some script we write but Infra hosts) will
# monitor every lucene-solr git commit
# if branch in not master, or a release branch, or if commit does not modify
refguide, then exit
# checkout the branch
# build ref-guide using ant, jekyll etc
# publish the resulting guide to the website under correct sub folder (see
above).
#* Alternatively, publish to some other place such as www.solr-guide.com or
wherever we want really.
# if JIRA issue mentioned in commit message, also add a comment to the JIRA
issue with a link to the newly built version of the guide.
#* Could even generate a list of deep-links to the individual guide pages
changed by the commit, for easier review.
# if the build of the refguide fails, then post to the JIRA issue a relevant
error message
The online, semi-live versioned copies of the guide should include a JS which
alerts the user if he is looking at an old version of the guide or an
unreleased version. In such a warning note, we could provide a link to current
version and a dropdown to switch between all existing versions.
Perhaps we could learn some tricks from other Apache projects already using
Asciidoc as well?
> 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]
