[doc] Add notes about compatibility and release process

[the-glu]

This PR adds to the documentation a method for performing upgrades, along with a compatibility matrix between recent DSS releases. This contributes to #1598 and is related to #1624 .

We should probably update this page as well as add the matrix to the release. However, we cannot add it to the release documentation, since we need the release itself to run the tests on the official image. Should we try to find a workaround, or assume that master will be up to date rather than the release's documentation?

The release procedure will need to be updated as well, once the previous point is settled.

[barroco]

Thanks @the-glu for preparing this. See my comments inline.

[the-glu]

@barroco Thanks for the review, a improved version is ready for a second pass

[barroco]

@the-glu, many thanks!

[BenjaminPelletier]

I think this is a great start and fine to add as-is. I think many of my comments are somewhat important, but they could potentially all be addressed in a followup PR if more convenient.

[BenjaminPelletier]

It seems like we need instructions to do this and we need to update https://github.com/interuss/dss/tree/master/release to reflect this necessary task when releasing (and, separately, it seems like we need to link to that page from https://github.com/interuss/dss/blob/master/RELEASE.md)

I don't think it will be important to users interested in upgrading how we generated or validated our documentation, just that it is correct. I think this section can be entirely moved to https://github.com/interuss/dss/tree/master/release and tweaked to read as an explanation for what run-compat-matrix.sh does and why.

[the-glu]

Yes, there is a linked PR #1624 in draft that helped generated part of this document. When it done I will update it to reflect what we want there, and I expect instructions to be part of that PR as well a this point.

I think what is left there is important for the user: the version used, the datastore, the migrations, the flags used and what tests that have been run, do you sill think it should be removed?

[BenjaminPelletier]

The user wants to know if two versions are compatible and it seems like that question is already answered in the table above without this information. If the answer above depends on flags used, what tests have been run, etc, then it seems like those caveats should be included in the answer somehow; the user shouldn't be given an answer whose interpretation depends on knowing how that documentation was written. The documentation-generation methodology is relevant to InterUSS contributors/developers, but I don't think it should be relevant to users, and this document is user documentation.

[the-glu]

I removed the section, but I still think it was somehow relevant. The documentation cannot validate every scenario with all possible combinations. We present the base, common case; if users deviate from that, they should run their own tests. This section explained how to do so.

[BenjaminPelletier]

The user wants to know if two versions are compatible and it seems like that question is already answered in the table above without this information. If the answer above depends on flags used, what tests have been run, etc, then it seems like those caveats should be included in the answer somehow; the user shouldn't be given an answer whose interpretation depends on knowing how that documentation was written. The documentation-generation methodology is relevant to InterUSS contributors/developers, but I don't think it should be relevant to users, and this document is user documentation.

[barroco]

As discussed offline with @BenjaminPelletier, this PR can be merged and additional/unadressed feedback will be addressed in follow up PRs. @the-glu please capture remaining items in issues if any.