From: Sebastian Wagner <sebastian.wagner@suse.com>
Date: Thu, 25 Jun 2020 10:31:36 +0000 (+0200)
Subject: python-common: service_spec.from_json: Add docstring explaining histroy
X-Git-Tag: v16.1.0~1916^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F35537%2Fhead;p=ceph.git

python-common: service_spec.from_json: Add docstring explaining histroy

Signed-off-by: Sebastian Wagner <sebastian.wagner@suse.com>
---

diff --git a/src/python-common/ceph/deployment/service_spec.py b/src/python-common/ceph/deployment/service_spec.py
index d53a2832e364..a041f4c53a74 100644
--- a/src/python-common/ceph/deployment/service_spec.py
+++ b/src/python-common/ceph/deployment/service_spec.py
@@ -426,6 +426,35 @@ class ServiceSpec(object):
         # then, the real type is: (dict) -> ServiceSpecs
         """
         Initialize 'ServiceSpec' object data from a json structure
+
+        There are two valid styles for service specs:
+
+        the "old" style:
+
+        .. code:: yaml
+
+            service_type: nfs
+            service_id: foo
+            pool: mypool
+            namespace: myns
+
+        and the "new" style:
+
+        .. code:: yaml
+
+            service_type: nfs
+            service_id: foo
+            spec:
+              pool: mypool
+              namespace: myns
+
+        In https://tracker.ceph.com/issues/45321 we decided that we'd like to
+        prefer the new style as it is more readable and provides a better
+        understanding of what fields are special for a give service type.
+
+        Note, we'll need to stay compatible with both versions for the
+        the next two major releases (octoups, pacific).
+
         :param json_spec: A valid dict with ServiceSpec
         """