On 08/26/2016 03:56 PM, Darren Hart wrote:
Property set revisions are intended to allow for new properties to
be
added in order to extend the functionality of a device. To preserve
compatibility between platform firmware and operating systems,
properties cannot be removed or modified, nor can new properties be
added unless they are marked as optional, in subsequent property set
revisions.
Update the language in process_rules.txt to make that clear. Remove the
paragraphs about firmware and operating system requirements to use the
latest revision and fall back to previous revisions as it is no longer
relevant with the clarified language.
Signed-off-by: Darren Hart <dvhart(a)infradead.org>
---
documentation/process_rules.txt | 28 +++++++---------------------
1 file changed, 7 insertions(+), 21 deletions(-)
diff --git a/documentation/process_rules.txt b/documentation/process_rules.txt
index 3458df0..bf8cb08 100644
--- a/documentation/process_rules.txt
+++ b/documentation/process_rules.txt
@@ -188,27 +188,13 @@ Changes to an accepted property set are only allowed if:
The only way in which one property set can be superseded by another one
is to register a new revision of the property set in question.
-Moreover, when creating a new revision of a property set, it is invalid
-to redefine property keys (that is, associate them with different data
-types or give them different meaning). New revisions can only add
-properties to the set. If one of the properties in the current (most
-recent) revision of a property set is to be deprecated in the next
-revision, the correct way to do that is to remove it from the new set
-entirely and define a new property with a new key as a replacement for
-it.
-
-If there are multiple revisions of a property set registered, platform
-firmware is required to provide properties from the most recent one.
-However, for the sake of backwards compatibility with existing Operating
-Systems, it may also provide properties that are not present in the most
-recent revision of the set, but were present in the previous revisions
-of it.
-
-Operating Systems are required to use properties from the most recent
-revision of a property set they are aware of. However, if those
-properties are not provided by platform firmware, the OS may fall back
-to using properties from the previous revisions of the property set that
-are not present in the most recent one.
+When creating a new revision of a property set, it is invalid
+to remove or redefine property keys (that is, associate them with
+different data types or give them different meaning). Properties may be
+added to new revisions, but those properties must be considered optional
+to preserve compatibility with platforms already shipping the previous
+revision. If properties need to be removed or modified, a new property
+set should be created and associated with a different device ID.
9. References
Applied. Thanks!
--
ciao,
al
-----------------------------------
Al Stone
Software Engineer
Red Hat, Inc.
ahs3(a)redhat.com
-----------------------------------