On Fri, Nov 12, 2021 at 8:55 PM David Jencks <david.a.jen...@gmail.com> wrote: > > > > > On Nov 12, 2021, at 11:20 AM, Zoran Regvart <zo...@regvart.com> wrote: > > > > Hi Cameleers, > > Our current practice is that over time we would remove older versions > > of documentation, we do this usually after a release of the new > > version. We keep the LTS versions but we remove the older visions. > > Sometimes we do this vigilantly, sometimes it takes a while till we > > notice that an older version is still being published. > > > > Overall we do this for one primary reason, the build performance is > > directly tied to the number of Antora components/branches being built. > > If the build took a constant amount of time, regardless of the number > > of components/branches being built we would probably leave more older > > versions around. There is also some maintenance to keeping older > > versions in case where we make a change on the website that is not > > backward compatible and it breaks the older version -- but I don't > > think we have had this issue thus far. > > > > This has recently been discussed (on Zulip or a GitHub issue, I can't > > seem to find), a Camel user was asking about older versions of the > > documentation; and again in the last few days the build was failing as > > we pointed to an older version of the documentation from one of the > > blog posts. > > > > I think we should discuss how we handle this, and explain our policy > > somewhere on the website. > > > > What do you think, should we keep doing as we have been doing and > > remove older versions? Should we keep all/more versions around? Can > > someone think of a way we could keep the older versions around and not > > jeopardize the build performance? > > There might be a way to keep older versions around without building them. > Dan Allen came up with what he calls a “site manifest” which is a json file > with all the pages in a site listed with enough info that xrefs to them can > be computed. His original motivation was a “sharded site” which I think means > there’s a big main site and then a supplemental site, not referenced from the > main site, but with links to the main site. The site manifest from the main > site lets xrefs from the subsidiary site to the main site be resolved. > > I’ve turned this into an Antora extension (with some modifications) and have > been using it to have quick partial builds of the camel site, something I > intend to talk about soon.
Oh, that sounds really interesting. > I think we can use it sort of in reverse to publish a site manifest for each > obsolete component version and use it to add to the component explorer. It > will take some thinking and a bit of work but should not be too hard. Hmm I need to wrap my head around this, sounds like we would build the version against the site manifest and never build it again? How's that different from building it, keeping the HTML files around and then removing that version from the playbook? We use hash of the CSS files for cache busting, so we'd need to keep the older version of CSS files as well. Not really an issue, just something we need to accomodate for. What would happen when an older version of the docs points to a page in the user manual that we removed/renamed? > I’d suggest that we do something to make it plain on each such page that the > page is obsolete, and in the component explorer that the version is obsolete. > This might involve a “final build” of the component version after a > “retirement update”. Maybe we could have an “obsolete” watermark in the > layout and set the “obsolete” layout in the antora.yml component descriptor. Yeah, I've seen banners displayed on older documentation pages prompting users to use the latest documentation/version, that would be helpful. I was also thinking about having a documentation ZIP distributed with the release downloads. Probably using a different Antora UI, perhaps a bit lighter and without the same menus as the published website. zoran -- Zoran Regvart
