Abstract Wikipedia team/Versioning
 | This page is currently a draft.
|
Versioning is hard. Versioning is important. The kinds of versioning we need for Wikifunctions are different from (and more complex than) the versioning needs people at Wikimedia already go through.
Types of versioning
[edit]There are different forms of versioning that we care about:
- Different versions of the functional model (e.g. previously a Z8/Function had a list of Z20/Testers as its Z8K4 key, but now it's a Map of Lists of Inputs to Results)
- Different versions of production software stack.
- More?
Approach for functional model changes
[edit]We are very careful to consider the functional model to be a public API of sorts. Post-launch, we will be very sparing with functional model changes, and avoid as much as possible making them in backwards-incompatible ways. (Pre-launch we may change it from time to time, without a versioning strategy.)
Our plan is to introduce a new root-level inherited implicit key, Z1K2, which will declare the functional model version used. If not defined, it will be assumed to be the latest version (whatever that is at run time). When new versions of the functional model are introduced, we will:
- Document in detail what the new value of Z1K2 means in practice, then
- Adjust the code for all parts of the system to understand the new value of Z1K2 and how to function with the new and former versions, then
- Test that the new value produces the correct results in a range of tests in production, then
- Throw a feature switch to enable the new version in production by default when using the Wikifunctions.org UX, then
- Throw a feature switch to start emitted deprecation warnings when the old version is used in production, then
- Drop support for the old version from production.
Multi-version support is expected to last for several weeks or more to allow time for clients to migrate over. We also expect to support more than one change at once in production (so e.g. production is running with code that supports version 5, 4, and 3 of the model; use of 3 will trigger a deprecation warning, whereas use of 4 will not, and use of 5 will be the majority of all use).
In extreme circumstances it's possible that it won't be feasible to support old functional models for very long or at all.
Approach for production software stack deployments
[edit]Different parts of the Wikifunctions software stack are deployed atomically, distinct from each other. This means that a new version of the evaluator might enter production with novel code that the corresponding code in the orchestrator and/or the WikiLambda UX don't yet support. Consequently, all breaking changes must be written in a forwards- and backwards-compatible way, where the release of a new version of the orchestrator doesn't break the existing evaluators, but they can be upgraded later when needed.
To achieve this, we are going to need solid end-to-end tests that would otherwise break when the upgrade happens. When adding new changes to functionality, we don't just adjust the tests to match, but add tests with the old mechanism and the new and make sure both continue to work, with a follow-up task to later drop the old mechanism once the whole stack has upgraded and definitely won't regress.