From 269e364086669962f37f045cf30f8f0f3cf6254c Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Sun, 7 Jul 2024 13:59:15 +1000 Subject: [PATCH] doc/dev: edit "Principles for format change" Improve "Principles for format change" in doc/dev/encoding.rst. This commit started as a response to Anthony D'Atri's suggestion here: https://github.com/ceph/ceph/pull/58299/files#r1656985564 Review of this section suggested to me that certain minor English usage improvements would be of benefit. The numbered lists in this section could still be made a bit clearer. Co-authored-by: Anthony D'Atri Signed-off-by: Zac Dover (cherry picked from commit 570797e5588b67b8c72e5297b61f84d9aa48dc45) --- doc/dev/encoding.rst | 49 ++++++++++++++++++++++---------------------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/doc/dev/encoding.rst b/doc/dev/encoding.rst index 29f1db81ab681..1a4967a477376 100644 --- a/doc/dev/encoding.rst +++ b/doc/dev/encoding.rst @@ -30,36 +30,35 @@ by a programmer by implementing the ``encode`` and ``decode`` methods. Principles for format change ---------------------------- -It is not unusual that the format of serialization changes. This -process requires careful attention during both development +It is not unusual for the format of serialization to change. This +process requires careful attention both during development and review. -The general rule is that a decoder must understand what had been -encoded by an encoder. Most of the problems come from ensuring -that compatibility continues between old decoders and new encoders -as well as new decoders and old decoders. One should assume -that -- if not otherwise derogated -- any mix (old/new) is -possible in a cluster. There are 2 main reasons for that: - -1. Upgrades. Although there are recommendations related to the order - of entity types (mons/osds/clients), it is not mandatory and - no assumption should be made about it. -2. Huge variability of client versions. It was always the case - that kernel (and thus kernel clients) upgrades are decoupled - from Ceph upgrades. Moreover, proliferation of containerization - bring the variability even to e.g. ``librbd`` -- now user space - libraries live on the container own. - -With this being said, there are few rules limiting the degree -of interoperability between dencoders: +The general rule is that a decoder must understand what has been encoded by an +encoder. Most difficulties arise during the process of ensuring the continuity +of compatibility of old decoders with new encoders, and ensuring the continuity +of compatibility of new decoders with old decoders. One should assume -- if not +otherwise specified -- that any mix of old and new is possible in a cluster. +There are two primary concerns: + +1. **Upgrades.** Although there are recommendations related to the order of + entity types (mons/OSDs/clients), it is not mandatory and no assumption + should be made. +2. **Huge variability of client versions.** It has always been the case that + kernel upgrades (and thus kernel clients) are decoupled from Ceph upgrades. + Containerization brings variability even to ``librbd`` -- now user space + libraries live in the container itself: + +There are a few rules limiting the degree of interoperability between +dencoders: * ``n-2`` for dencoding between daemons, -* ``n-3`` hard requirement for client-involved scenarios, -* ``n-3..`` soft requirements for client-involved scenarios. Ideally - every client should be able to talk any version of daemons. +* ``n-3`` hard requirement for client scenarios, +* ``n-3..`` soft requirement for client scenarios. Ideally every client should + be able to talk to any version of daemons. -As the underlying reasons are the same, the rules dencoders -follow are virtually the same as for deprecations of our features +As the underlying reasons are the same, the rules that dencoders +follow are nearly the same as the rules for deprecations of our features bits. See the ``Notes on deprecation`` in ``src/include/ceph_features.h``. Frameworks -- 2.39.5