Common configuration patterns draft text

spec/src/main/asciidoc/config.asciidoc

@@ -0,0 +1,147 @@
+//
+// 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 application class names are prefixed with "mp." followed by the specification's short name:  `mp.<spec-name>`.
+
+----
+// For example, the Messaging Specification has an @Outgoing annotation:
+   mp.messaging.outgoing.attributename=3
+----
+
+[[qualifyingClassNames]]
+==== Properties That Relate To Application Classes
+
+All references to users' application classes in property names should be fully package qualified.
+
+There are places where an annotation class name appears or a specification sourced class name (e.g. Context Propagation) appears in configuration property names, these class names are not package qualified. Should these start with `mp.<spec-name>`? In this case `mp.ft`?
+----
+// 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. 
+
+[[fieldAnnotations]]
+==== Properties That Relate To Annotated Fields
+
+Is is possible to override attributes of annotated fields. In this case the following
+pattern is recommended: `<fully qualified class name>/<field name>/<spec-defined annotation name>/<annotation attribute name>`.
+----
+// For example:
+   com.acme.ClassA/methodB/Retry/maxRetries=5
+----
+
+[[methodAnnotations]]
+==== Properties That Relate To Annotated Methods
+
+For annotated application methods, these are expected to be overridden
+with the following pattern: `<fully qualified class name>/<method name>/<spec-defined annotation short name>/<annotation attribute name>`.
+----
+// For example:
+   com.acme.ClassA/methodB/Retry/maxRetries=5
+----
+
+[[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
+does not have a recommended approach yet.
+
+[[parameterAnnotations]]
+==== Properties That Relate To Annotated Parameters in Application Methods
+
+Parameter names are not guaranteed to be available during annotation processing.
+Due to this, it can be problematic to rely on parameter names for annotations that
+relate to application methods.
+An annotated application method parameter can be referred to using a positional index, starting at '1'. `<fully qualified class name>/<method name>/<parameter position>/<spec-defined annotation short name>/<annotation attribute name>`.
+----
+// For example, the '1' below refers to the first parameter:
+   com.acme.order.OrderProcessing/setSomething/1/SomeMicroProfileAnno/someAttribute=5
+----
+
+[[scopedOverriding]]
+==== Properties That Override for 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 - no recommended pattern as yet
+- package - `<dotted-fully-qualified-package>/<annotation-classname>/<parameter>` (no application class or method name)
+- archive - no recommended pattern as yet
+- service - [`mp.service-shortname.`]`<annotation-or-classname>/<parameter>`
+- globally - same as service
+- named - where an annotation occurrence is named - no recommended pattern as yet
+
+[[overridingPrecedence]]
+==== Overlapping Configuration Scopes Precedence
+
+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>`.
+
+[[codeEnvPrecedence]]
+==== Code Versus Process Environment Configuration Precedence 
+
+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 [Move to Config Spec]
+
+(This topic is likely to be handled in a future version of the Configuration specification.)
+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

@@ -45,4 +45,6 @@ include::architecture.asciidoc[]
 
 include::required-apis.asciidoc[]
 
+include::config.asciidoc[]
+
 include::notices.asciidoc[]