Repository navigation
Release Compatibility Documentation #1598
Description
Activity
Adding that information in the release notes (and/or documentation) seems a good idea indeed.
For the current situation / release until it's done, should that help:
I didn't explicitly tested combinations (I will do in the PR with details), but recent releases (at least 0.23.0-rc2 -> 0.20.0) should be compatible with others recent releases. Schema updates only include new functionalities / improvements and are backward compatible with old version of the code. In general, the expected procedure is: upgrade the schema and rollout restart the DSS with new images.
I think this is an important element to support nominal operational usage of the DSS. The user journey I think this documentation would primarily serve is "I am part of a DSS pool in State X. We want to change to State Y. What is the procedure we should follow to get from X to Y?" "State X" would be something like all instances are running v0.20.0 with SCD schema v3.2.0 and "State Y" would be something like all instances are running the v0.23.0 with the corresponding recommended SCD schema.
There are many forms the answers to this kind of question could take, but I would envision something like a compatibility table plus explanatory text like "The DSS version is expected to be the same across all instances in general, but a pool should continue to operate normally for periods of up to about a week (actual value TBD) when the pool contains DSS version combinations as indicated in the table:"
v5 v4 v3 v2 v1 v5 * SCD schema v3
* No operations should be performed when --flag1 is inconsistent between instances* SCD schema v3
* --flag1 not setNot supported Not supported Not supported v4 * SCD schema v2-v3
* SCD schema v3 recommended* SCD schema v2-v3 * SCD schema v2 Not supported v3 * SCD schema v2-v3 * SCD schema v2 Not supported v2 * SCD schema v1-v2 * SCD schema v1-v2 v1 * SCD schema v1-v2 Example table usage for "I am part of a DSS pool all with DSS v1 + SCD schema v1. We want to change to DSS v5 + SCD schema v3 with --flag1 set." would start by noticing that co-existence of v5 and v1 DSS instances in the same pool is not supported. The first step could either be to update all instances to v2 (because v1 and v2 can temporarily co-exist in a pool at SCD schema v1) or update the SCD schema to v2 (because a pool of all v1 DSS instances can operate with SCD schema v2). If the first step were to update to SCD schema v2, the second step could then be to jump straight to v4 (each instance updating from v2 to v4 at its convenience) since v2 and v4 can co-exist in a pool at SCD schema v2. Once all instances were updated to v4, the SCD schema could then be updated to v3 since DSS v4 supports SCD schema v3. Then, all DSS instances could be leisurely updated to v5, but without --flag1 set, since v4 and v5 can co-exist in a pool at SCD schema v2 as long as --flag1 isn't set. Then, once all DSS instances were v5, the "no --flag1" restriction no longer applies so the DSS instances could enable --flag1, but the note says this would need to be a coordinated action since no operations should be performed on the pool while the value for this flag is inconsistent.
This information would presumably live permanently in user documentation in the repo itself since compatibility information for earlier releases will be added later (e.g., DSS v1 above is compatible with SCD schema v2 which didn't exist when DSS v1 was released). But, we could add initial equivalent information to the v0.23.0 release notes before the permanent documentation is developed if that would more expeditiously meet the need. We could also make something like the table above for only the more recent versions (e.g., starting at v0.21.0, or whatever the oldest version is reported by users to be in operation) before or instead of extending it all the way back to all older versions.
As a side note, I believe InterUSS has so far successfully maintained a "stair step" ability to climb the DSS/schema upgrade ladder leisurely without needing coordinated action from all participants in the DSS pool to avoid downtime. And, it is our objective to continue that practice if reasonably possible.
I missed that #1631 was already associated with this Issue and think its content addresses my comments modulo some specific comments I'll make on that PR.
Feature Request
Is it possible going forward to document in the release notes of each new candidate what the earliest backwards compatible previous release candidate is?
Backwards compatible here meaning that two DSS deployments in the same pool could be running these different releases without impacting performance or safety critical functions of the DSS.
If there is general guidance (e.g. all minor version updates within the same major version are compatible, versions are compatible if there is no schema change...) that would also help
Additional context
For context, we are not planning to run different DSS versions within the same pool for an extended period of time but this would help DSS hosts come up with a thoughtful rollout plan and cutover period when upgrading to new software releases without affecting production flights.