Yeah that's a good point. It'd be an easy way to end up with broken links.

That said, why do we write the developer docs as a separate document? A lot of projects keep them as the same document, but just separated at the top level of the table of contents. Could we consider merging them into the same Sphinx document so that it's easier to link to API changes in our release notes? Is there a benefit to keeping them separate that you can think of?