From f17a1ce37cce4f0950c330820a41077456a0f897 Mon Sep 17 00:00:00 2001 From: Adam Spiers Date: Thu, 25 Apr 2019 12:16:13 +0100 Subject: [PATCH] Document policy of never removing traits It has been asked at least twice in recent weeks (the first time by me) why unused traits can't be removed from os-traits: http://eavesdrop.openstack.org/irclogs/%23openstack-nova/%23openstack-nova.2019-04-18.log.html#t2019-04-18T17:59:58 http://eavesdrop.openstack.org/irclogs/%23openstack-nova/%23openstack-nova.2019-04-25.log.html#t2019-04-25T10:48:18 so let's explicitly document this policy to prevent future generations getting confused, or worse, attempting to remove traits. Change-Id: I4028c25ff5fc0adeca6ee62b0db11d8bbf909f28 --- doc/source/contributor/index.rst | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index 3d4ceb4..f1597df 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -2,4 +2,29 @@ Contributing ============ + +Trait lifecycle policy +====================== + +It is the policy of this project that once registered, traits should +never be removed, even those which will never be used by code (e.g. as +a result of pivots in design or changes to the namespaces). + +The general principle behind this policy is simply that an +extensible-only enumeration is easier to manage than one than can be +shrunk. One particular example concerns the need for the placement +service to keep its database in sync with the strings in os-traits. +Whenever a placement service sees a new version of os-traits it syncs +up its database with the strings that are in the package, creating a +row in the traits table, with an id that becomes a foreign key in other +tables. If traits could be removed, then extra clean-up code might be +needed in several places to handle this, and this would be +particularly error-prone when execution of that code would need to be +correctly orchestrated across multiple projects. + + +Generic instructions for contributing +===================================== + + .. include:: ../../../CONTRIBUTING.rst