@tomponline any additional sections you'd like to see here before I request reviews, or perhaps more detail in a particular section?

The tests should pass once #14600 is merged.

The tests should pass once #14600 is merged.

As I mentioned in that PR, the fix implemented there causes other issues.

I assume this is the test failure you're wanting to fix:

WARNING: reference/vm-live-migration-internals: 404 Client Error: Not Found for url: https://discuss.linuxcontainers.org/t/50734.json [canonical-sphinx-extensions.linktext]

where you want to direct to the Ubuntu discourse article and not a LinuxContainers one.

That should be fixed by using the ubuntu prefix:

discourse: ubuntu:50734

in line 2 of vm-live-migration-internals.md in this PR, without need of #14600

Furthermore, to make sure that we don't rely on fetching the page title at build, which can cause the build to fail if the Ubuntu Discourse is down, add the title statically. The related-links extension we use requires replacing spaces in the title with  , so that will look like this:

discourse:ubuntu:[Online VM live-migration (QEMU to QEMU)](50734)

Per conversation with @kadinsayani, I understand that the intent of #14600 is to update the discourse links so that the Ubuntu one is the default (and eventually only) discourse used for related links. If it is merged as the default, you wouldn't need to use discourse:ubuntu and could use just discourse: instead.

However, you'd at least want to use the static title, for the build failure reasons I mentioned:

discourse:[Online VM live-migration (QEMU to QEMU)](50734)

If we aren't migrating all the lxc links to ubuntu at this time/not switching the default discourse, then you will need to specify discourse:ubuntu.

Thanks for all your feedback @simondeziel!

I'm going to reword the steps to make things more clear.