I am involved in a bunch of open source projects that all have documentation sites on netlify.
A common problem for all of them is that their master branch contains all the latest changes, including breaking ones and the docs usually follow along. So all of them want to employ semver to their documentation site in a way where upcoming breaking changes don’t leak through to the documentation before it’s relevant.
Furthermore, when dealing with breaking changes in new versions, there are still a lot of users on older major versions. It would be extremely useful to be able to keep the latest version of each major version branch alive as on their documentation site, so you could easily access the version of the documentation relevant to you.
Is there a way to set up Netlify that would allow for easy versioning, creating branch deployments for each older major version and possibly routing them through /versions/vx.y.z, possibly also with /versions/vx redirecting to the latest semver release under that major version?
I am aware that some local scripting would be needed, for example to get the released versions out of git tags, or through branch names with special naming conventions in order to generate links to the old versions and possibly also to generate netlify config files.
I would love to see an example implementation of this
I don’t have a good example implementation, since they’d depend quite heavily on how you handle and publish releases. Two workflows I am aware of people using:
use semver directory structure and duplicate unchanged content in /1.1, /1.2, /1.3 . This would require that you have a git workflow where you do this already, since I’m not trying to suggest you restructure your repo or release process. Then the deploy just works. You might have “default” be the last stable version by pointing your main index.html there rather than to actual-latest-version that could be in beta or not-quite-released-yet.
another workflow that I am aware of someone using is branch deploys + subdomains, so each semver is a branch, and they effectively have hundreds of branches one per version and all their docs are linked in a version-first way (index is a table of contents and each link goes to https://branch-1-1-1--theirsite.netlify.com aka branch-1-1-1.theirsite.com, https://branch-1-1-2--theirsite.netlify.com etc). That is a bit challenging as updating the look and feel of the site at branch-2-0-0 won’t be “automatically backported” to branch-1-1-x that are effectively frozen in time, but it does allow you to manually merge design changes back into those branches if that is important to you.
There are dozens of other ways to do it, but hopefully those two that I’ve seen work (though I apologize I can’t link to them) will inspire and inform.
If you end up using separate netlify sites for each branch, that is also an option - you are allowed to configure multiple sites against the same repo using different branches, and then you could try something like proxying between them for just the semver-specific content: