Published Spec URLs

William Bartholomew (CELA)

I’m making some changes to the CI/CD to allow us to automatically publish side by side versions of the docs and to centralize that build and publishing process (so it’s not spread across the branches).


We have a few types of docs we publish:

  1. Releases (v2.3.0) created on demand from a tag (tags/v2.3.0)
  2. Preview releases (v2.3.0-rc1) created on demand from a branch (heads/v2.3)
  3. Latest draft of a development branch (v2) created on each commit to a branch (heads/v2.3)
  4. Previews for pull requests to help people review and/or verify publishing works and looks correct (commits/a1b2c3) – we don’t do this today


I’d like to make this process as consistent as possible so I’m proposing the following:

  • We’ll treat preview releases just like releases and create tags for them (e.g. tags/v2.3.0-rc1) – this means that #1 and #2 will build with the same process and will give added confidence that the release matches the release candidates (they two tags will point at the same commit if there’s no changes after the last RC).
  • The versions will all sit in the same URL namespace (e.g. would be a published release, would be a published pre-release, and would be a continuously updated link for the development/v2.3 branch).
  • Add aliases “latest” ( that points at the most recent build of vCurrent-dev and “stable” ( that points at the most recent release.


Let me know ASAP if you have any concerns with this.




William Bartholomew (he/him) – Let’s chat

Principal Security Strategist

Global Cybersecurity Policy – Microsoft


My working day may not be your working day. Please don’t feel obliged to reply to this e-mail outside of your normal working hours.