Kevin Wolf <kwolf@xxxxxxxxxx> writes: > Am 26.10.2021 um 11:37 hat Markus Armbruster geschrieben: >> Kevin Wolf <kwolf@xxxxxxxxxx> writes: >> >> > Am 25.10.2021 um 07:25 hat Markus Armbruster geschrieben: >> >> By convention, names starting with "x-" are experimental. The parts >> >> of external interfaces so named may be withdrawn or changed >> >> incompatibly in future releases. >> >> >> >> Drawback: promoting something from experimental to stable involves a >> >> name change. Client code needs to be updated. >> >> >> >> Moreover, the convention is not universally observed: >> >> >> >> * QOM type "input-barrier" has properties "x-origin", "y-origin". >> >> Looks accidental, but it's ABI since 4.2. >> >> >> >> * QOM types "memory-backend-file", "memory-backend-memfd", >> >> "memory-backend-ram", and "memory-backend-epc" have a property >> >> "x-use-canonical-path-for-ramblock-id" that is documented to be >> >> stable despite its name. >> >> >> >> We could document these exceptions, but documentation helps only >> >> humans. We want to recognize "unstable" in code, like "deprecated". >> >> >> >> Replace the convention by a new special feature flag "unstable". It >> >> will be recognized by the QAPI generator, like the existing feature >> >> flag "deprecated", and unlike regular feature flags. >> >> >> >> This commit updates documentation and prepares tests. The next commit >> >> updates the QAPI schema. The remaining patches update the QAPI >> >> generator and wire up -compat policy checking. >> >> >> >> Signed-off-by: Markus Armbruster <armbru@xxxxxxxxxx> >> > >> > Obviously, replacing the old convention gets rid of the old drawbacks, >> > but adds a new one: While using x- makes it very obvious for a human >> > user that this is an unstable feature, a feature flag in the schema will >> > almost certainly go unnoticed in manual use. >> >> I thought about this, but neglected to put it in writing. My bad. >> >> Manual use of unstable interfaces is mostly fine. Human users can adapt >> to changing interfaces. HMP works that way. >> >> Management applications are better off with a feature flag than with a >> naming convention we sometimes ignore. >> >> The most potential for trouble is in between: programs that aren't >> full-fledged management applications. >> >> If we want to keep "unstable" obvious to the humans who write such >> programs, we can continue to require "x-", in addition to the feature >> flag. We pay for it with renames, and the risk of forgetting to rename >> in time (which is what got us the awkward stable >> "x-use-canonical-path-for-ramblock-id"). Tradeoff. I chose not to, but >> if y'all think we should... > > Just to clarify, I'm not implying that we should keep it. I'm merely > pointing out that there is a tradeoff that requires us to make a choice. > The decision for one of the options should be explicit rather than just > happening as a side effect. Documenting that it was a conscious decision > is probably best done by adding the reasoning for it to the commit > message. I rewrote the commit message for v2. Thanks! [...]
