this is a fairly open-ended question, so i’m just tossing it out here to try and get some input from others.
the problem
on the Swiftinit documentation index, we host a number of historical documentation archives, which were built using older versions of the toolchain. (“old” in this context means 5.9.2 or earlier)
these documentation archives use a binary format which we have some desire to make some breaking changes to, which entails recompiling the packages those older archives were generated from.
in an ideal world, it would be as simple as that — just regenerate the archives using a modern version of the documentation compiler, which ships with a 5.10 Swift compiler. but i have found that a high proportion of these snapshots do not build successfully with a 5.10 compiler, due to some regressions in the ownership features.
the solutions
in my mind, there are a few possible solutions here, and choosing the best one depends on what our expectations for swift source compatibility should be.
-
no expectation of source compatibility: we should replicate the original build invocation as closely as possible, which means recompiling the failing packages using an older Swift compiler. this means we would have to setup the builder node with multiple versions of the Swift toolchain installed, and have some way of tracking what packages build successfully with which versions of Swift.
this could be a decent stopgap, but wouldn’t really be sustainable in the long term, as newer and newer versions of the toolchain come out.
-
some expectation of source compatibility: we could declare as site policy that all documentation hosted on Swiftinit must originate from packages that compile successfully with the latest version of Swift. snapshots that fail to compile would be considered non-compliant, and documentation associated with those packages would be removed as newer versions of the toolchain come out.
today on Swiftinit, we have no process (or precedent) for unpublishing public documentation. whether or not we start removing documentation would depend on how that affects users of the site.
from my own unscientific analysis, a lot of the failing snapshots are highly experimental packages that use cutting-edge features like ownership and parameter packs, and they have a relatively small audience. the problem is also concentrated among historical docs, because actively-maintained packages generally receive updates that fix their 5.10 builds. but there are some packages which are not actively maintained and their documentation would disappear entirely if we introduced such a requirement.