Common configuration patterns draft text

spec/src/main/asciidoc/config.asciidoc

@@ -0,0 +1,126 @@
+//
+// Copyright (c) 2019 Contributors to the Eclipse Foundation
+//
+// See the NOTICE file(s) distributed with this work for additional
+// information regarding copyright ownership.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+[[config]]
+== Common Configuration Patterns
+
+Many MicroProfile specifications make use of the Configuration specification for
+setting or overriding behaviour characteristics. Listed below are a list of recommended usage
+patterns that are already adopted by one or more of the MicroProfile specifications.
+
+[[patterns]] 
+=== Patterns
+
+[[propertyPrefix]]
+==== Configuration Property Name Prefixes
+
+In order to prevent collision it is recommended that properties that are not
+named to match user class names are prefixed with "mp." followed by the specification's short name:
+----
+mp.<spec-name>
+e.g. The Messaging Specification has an @Outgoing annotation:
+mp.messaging.outgoing.value
+----
+
+[[qualifyingClassNames]]
+==== Properties Names Representing User Class names Should Be Package Qualified
+
+There are places where an annotation class name appears or a specification sourced class name (e.g. Concurrency) appears in configuration property names, these class names are not package qualified: 
+----
+//For example: 
+   Retry/maxRetries=30
+//or should this be?
+   mp.ft.retry.maxRetries=30
+----
+This is probably the right choice from a usability point of view. 
+This is particularly not a problem where the scope of the configuration property identifies a particular Java file (which will have resolved the package name via an import).
+It could become more of a problem for service wide defaults if more than one MicroProfile service
+has a class with the same name. 
+The result is that we should have exclusive class names in MicroProfile for classes that might need configuration override in the process environment. 
+The 'first' specification that owns a class name should own that name exclusively. 
+
+Where user class names appear, these are expected to be package qualified.
+
+[[overloadedMethods]]
+==== Properties That Relate To Overloaded Methods
+
+There are places in the configuration where a method name is used. 
+Accounting for methods with the same name but different signatures
+can be done using indexing. 
+The "1" in the Property name below refers to the occurrence of the 'method' named 
+----
+`org.eclipse.microprofile.example.ExampleBean/setCompletableFuture/1/ManagedExecutorCon fig/maxAsync=5`
+----
+
+[[scopedOverriding]]
+==== Properties Overriding a Particular Scope.
+
+Various specifications consider overriding, either at particular annotation location, a particular class or
+service wide (treated as global). Overriding at different scopes should occur as follows: 
+
+The set of possible scopes is:
+
+- class - `<dotted-fully-package-qualified-classname>/<annotation-classname>/<parameter>`
+- package-prefix `<package-prefix>.*` ( `*` is not a valid ENV variable char)
+- package - `<dotted-fully-qualified-package>/<annotation-classname>/<parameter>` (no user class or method name)
+- archive - not specified yet
+- service - [`mp.service-shortname.`]`<annotation-or-classname>/<parameter>`
+- globally - same as service
+- named - Where an annotation occurrence is named - not specified yet.
+
+[[overridingPrecedence]]
+==== Precedence of Configuration Scope Overlap
+
+Configuration which is more specific overrides configuration where the scope is more general.
+
+For example, where multiple configuration properties are present, the property `<classname>/<methodname>/<annotation>/<parameter>` takes precedence over `<classname>/<annotation>/<parameter>`, which would take precedence over `<annotation>/<parameter>`.
+
+[[indexingOverrides]]
+==== Indexing Annotation Occurrences (from Concurrency)
+
+The "1" in the Property name below refers to the first occurrence of the 'method' named `setCompletableFuture`
+---- 
+`org.eclipse.microprofile.example.ExampleBean/setCompletableFuture/1/ManagedExecutorCon fig/maxAsync=5`
+----
+
+[[codeEnvPrecedence]]
+==== Precedence of Configuration Overlap - Code Versus Process Environment
+
+Configuration from the environment overrides configuration in the code for all configuration
+of equal of less specific scope in the code. For example, the property `<classname>/<methodname>/<annotation>/<parameter>` takes precedence over `<classname>/<annotation>/<parameter>`, which is followed by `<annotation>/<parameter>`.
+
+----
+Should code sited configuration that is more specific than process environment configuration take precedence? Or should environment configuration overrule coded configuration for all scopes it applies to?
+----
+
+[[ignoredProperties]]
+==== Overrides Are Ignored if No Matching Annotation Is Present
+
+Overrides change the value of the corresponding annotation parameter specified in a microservice. If no annotation is present which matches the specified configuration property, the property will be ignored.
+
+[[empty]]
+==== Indicating An Empty Set 
+
+In order to guarantee that empty string configuration values are interpreted consistently, the following
+configuration values, as defined by the Configuration specification indicating empty:
+
+- an empty array
+- an array containing the empty String as its singular element
+

spec/src/main/asciidoc/microprofile-spec.asciidoc

@@ -43,6 +43,8 @@ include::license-alv2.asciidoc[]
 
 include::architecture.asciidoc[]
 
+include::config.asciidoc[]
+
 include::required-apis.asciidoc[]
 
 include::notices.asciidoc[]