> 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.
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.
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.
David Jencks
