Easy to forget to copy changes to newer sdf/1.X folders when merging forward

[scpeters]

Description

I have noticed several pull requests that add features or fix documentation to a version of the SDFormat specification contained in the sdf/1.X folders that doesn't get propagated to newer folders when merging forward. For example, camera type aliases were added to the documentation of sdf/1.6/camera.sdf and sdf/1.7/camera.sdf in #514, but were not added to sdf/1.8/camera.sdf when merged forward to sdf11 in #520. This is easy to forget and not documented as part of our forward porting policy. We should determine an improved process and document it. If possible, we could try to create automated testing to remind us about this, though I'm not sure how.

[FirefoxMetzger]

@scpeters One option could be to merge all sdf/1.X descriptions into a single description and introduce //versionadded, //versionchanged, and //depreciated, similar to what sphinx is doing in rst.

The full signature of the elements could be something like

<versionadded ver="1.X">Description of new feature (see also this issue/PR), e.g., Added the @degrees attribute (#589).</versionadded>
<versionchanged ver="1.X">Description of how the behavior of this element has changed and, possibly, how to upgrade or keep the old behavior. (potentially link to PR/issue)</versionchanged>
<depreciated ver="1.X">Migration instructions on how to substitute the depreciated element.</depreciated>

With these elements added to the meta-language, you can choose how to respond to them when generating docs/xsd/etc. You could keep the current doc structure and simply ignore all elements with a higher //versionadded or lower //depreciated version and add all the //versionchanged texts as additional description to the docs where applicable. Alternatively, you can have a single version of the docs that shows everything and potentially add filters for the tags that hide unavailable elements for a specific version (deprecated/added later).

Either way, you get a clean dev environment where you only maintain a single version and where all changes forward/backward port directly.

[scpeters]

@scpeters One option could be to merge all sdf/1.X descriptions into a single description and introduce //versionadded, //versionchanged, and //depreciated, similar to what sphinx is doing in rst.

that sounds pretty nice