From 731c2b6c2180f7a33210dfbeeb4b7c47219da400 Mon Sep 17 00:00:00 2001
From: Victor Woeltjen <victor.woeltjen@nasa.gov>
Date: Wed, 7 Jan 2015 17:18:39 -0800
Subject: [PATCH] [Framework] Document extension ordering rules

Add a description of priority-ordering rules (implemented for WTD-590)
to framework documentation.
---
 platform/framework/README.md        | 31 +++++++++++++++++++++++++++++
 platform/framework/src/Constants.js |  7 ++++---
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/platform/framework/README.md b/platform/framework/README.md
index 0089ede522..f359a12f12 100644
--- a/platform/framework/README.md
+++ b/platform/framework/README.md
@@ -106,6 +106,37 @@ support for the category of extension being registered.
   list, with Angular-level dependencies are declared, and the full set
   is exposed as a single Angular "service."
 
+### Priority order
+
+Within each category, registration occurs in priority order. An extension's
+priority may be specified as a `priority` property in its extension
+definition; this may be a number, or a symbolic string. Extensions are
+registered in reverse numeric order (highest-priority first), and symbolic
+strings are mapped to the numeric values as follows:
+
+* `fallback`: Negative infinity. Used for extensions that are not intended
+  for use (that is, they are meant to be overridden) but are present as an
+  option of last resort.
+* `default`: -100. Used for extensions that are expected to be overridden, but
+  need a useful default.
+* `none`: 0. Also used if no priority is specified, or if an unknown or
+  malformed priority is specified.
+* `optional`: 100. Used for extensions that are meant to be used, but may be
+  overridden.
+* `preferred`: 1000. Used for extensions that are specifically intended to
+  be used, but still may be overridden in principle.
+* `mandatory`: Positive infinity. Used when an extension should definitely
+  not be overridden.
+
+These symbolic names are chosen to reflect usage where many extensions may
+satisfy a given usage, but only one may be used; in this case, as a
+convention it should be the lowest-ordered (highest-priority) extensions
+available. In other cases, a full set (or multi-element subset) of
+extensions may be desired, with a specific ordering; in these cases, it
+is preferable to specify priority numerically when declaring extensions,
+and to understand that extensions will be sorted according to these
+conventions when using them.
+
 ### Composite services
 
 Composite services are assumed to follow a provider-aggregator-decorator
diff --git a/platform/framework/src/Constants.js b/platform/framework/src/Constants.js
index 13eb346448..4ac8941ee0 100644
--- a/platform/framework/src/Constants.js
+++ b/platform/framework/src/Constants.js
@@ -19,9 +19,10 @@ define({
     },
     PRIORITY_LEVELS: {
         "fallback": Number.NEGATIVE_INFINITY,
-        "default": 100,
-        "optional": 200,
-        "preferred": 400,
+        "default": -100,
+        "none": 0,
+        "optional": 100,
+        "preferred": 1000,
         "mandatory": Number.POSITIVE_INFINITY
     },
     DEFAULT_PRIORITY: 0