From 80191640dd166603108761d76c2e3fedd0ea4d34 Mon Sep 17 00:00:00 2001
From: Dmitry Kornilov <dmitry.kornilov@oracle.com>
Date: Thu, 2 Feb 2023 12:07:26 +0100
Subject: [PATCH] Introduction section

Signed-off-by: Dmitry Kornilov <dmitry.kornilov@oracle.com>
---
 spec/pom.xml                                  |  2 +-
 spec/src/main/asciidoc/01-introduction.adoc   | 54 +++++++++++++++++++
 spec/src/main/asciidoc/02-config.adoc         |  7 +--
 .../{01-config-spec.adoc => config-spec.adoc} |  1 +
 4 files changed, 58 insertions(+), 6 deletions(-)
 create mode 100644 spec/src/main/asciidoc/01-introduction.adoc
 rename spec/src/main/asciidoc/{01-config-spec.adoc => config-spec.adoc} (97%)

diff --git a/spec/pom.xml b/spec/pom.xml
index f3874e4..cac66dd 100644
--- a/spec/pom.xml
+++ b/spec/pom.xml
@@ -121,7 +121,7 @@
                     </execution>
                 </executions>
                 <configuration>
-                    <sourceDocumentName>01-config-spec.adoc</sourceDocumentName>
+                    <sourceDocumentName>config-spec.adoc</sourceDocumentName>
                     <sourceHighlighter>coderay</sourceHighlighter>
                     <attributes>
                         <revnumber>${project.version}</revnumber>
diff --git a/spec/src/main/asciidoc/01-introduction.adoc b/spec/src/main/asciidoc/01-introduction.adoc
new file mode 100644
index 0000000..8ff6aa2
--- /dev/null
+++ b/spec/src/main/asciidoc/01-introduction.adoc
@@ -0,0 +1,54 @@
+== Introduction
+
+=== Scope
+
+Jakarta Config ("Specification") is a Java API for working with configurations. It supports externalized configuration allowing applications to use different configurations for different environments (dev, test, prod), and allows reading data from different layered configuration sources such as property files, environment variables, etc.
+
+=== Goals
+
+- Specification must include a programmatic API allowing configuring and using configurations at runtime.
+- Specification must include annotations based API allowing compile-time configuration.
+- Specification must support converters and evaluate switching to Converters specification when it becomes available.
+- Specification must support object-mapping. Solution must respect Java methods visibility principles.
+- Specification must provide integration with CDI and optionally with  dependency injection frameworks.
+- Specification must distinguish empty strings and null values.
+- Specification must support profiles such as dev, test and prod.
+- Specification must support both mutable and immutable configuration sources.
+- Specification must support flat and hierarchical configuration structure.
+- Configuration must explain how to deal with configurations stored in common file formats such as property files, yaml, json.
+
+=== Non-Goals
+
+- Blindly copy MicroProfile Config specification.
+- Blindly copy APIs from any of existing configuration frameworks.
+
+=== Resources
+
+- GitHub repository: https://github.com/eclipse-ee4j/config
+- Jakarta EE Specification Project: https://projects.eclipse.org/projects/ee4j.jakartaconfig
+- Mailing List: https://accounts.eclipse.org/mailing-list/config-dev
+
+=== Conventions
+
+The keywords 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in https://www.ietf.org/rfc/rfc2119.txt[RFC 2119].
+
+Java code and sample data fragments are formatted as shown below:
+
+[source,java]
+.Example Java Code
+----
+package com.example.hello;
+
+public class Hello {
+    public static void main(String args[]) {
+        System.out.println("Hello World");
+    }
+}
+----
+
+All parts of this specification are normative, except for examples, notes and sections explicitly marked as 'Non-Normative'. Non-normative notes are formatted as shown below:
+
+*Note:* _This is a note._
+
+=== Terminology
+
diff --git a/spec/src/main/asciidoc/02-config.adoc b/spec/src/main/asciidoc/02-config.adoc
index d517361..d81dd5f 100644
--- a/spec/src/main/asciidoc/02-config.adoc
+++ b/spec/src/main/asciidoc/02-config.adoc
@@ -1,9 +1,6 @@
-= Jakarta Config Specification
+== Specification
 
-== Introduction
-
-
-== Support Injection
+=== Support Injection
 A ConfigMapping interface can be injected via the `@Inject`. The following example demonstrates the usage.
 
 [source]
diff --git a/spec/src/main/asciidoc/01-config-spec.adoc b/spec/src/main/asciidoc/config-spec.adoc
similarity index 97%
rename from spec/src/main/asciidoc/01-config-spec.adoc
rename to spec/src/main/asciidoc/config-spec.adoc
index 25c7edb..116612d 100644
--- a/spec/src/main/asciidoc/01-config-spec.adoc
+++ b/spec/src/main/asciidoc/config-spec.adoc
@@ -36,4 +36,5 @@ endif::[]
 include::license-efsl.adoc[]
 
 :sectnums:
+include::01-introduction.adoc[]
 include::02-config.adoc[]