From e615fa42d4f06e87a1f56d5fcd25a156431a4038 Mon Sep 17 00:00:00 2001
From: Petr Šabata <contyk@redhat.com>
Date: May 05 2017 10:11:40 +0000
Subject: Add some clarifications to the specification


Signed-off-by: Petr Šabata <contyk@redhat.com>

---

diff --git a/spec.yaml b/spec.yaml
index abf529c..480a6a0 100644
--- a/spec.yaml
+++ b/spec.yaml
@@ -32,7 +32,7 @@ data:
             - MIT
         # Content license, optional
         # A list of licenses used by the packages in the module.
-        # This should be populated by build tools.
+        # This should be populated by build tools, not the module author.
         content:
             - Beerware
             - GPLv2+
@@ -51,12 +51,12 @@ data:
         # Keys are module names, values are the stream names
         # These modules define the buildroot for this module
         buildrequires:
-            generational-core: and-its-stream-name
-            generational-core-build: and-its-stream-name-too
+            platform: and-its-stream-name
+            extra-build-env: and-its-stream-name-too
         # Run-time dependencies of this module, optional
         # Keys are module names, values are their stream names
         requires:
-            generational-core: and-its-stream-name
+            platform: and-its-stream-name
     # References to external resources, typically upstream, optional
     references:
         # Upstream community website, if it exists, optional
@@ -93,16 +93,13 @@ data:
         # of this module. This is meant to be used on target systems where size
         # of the distribution is a real concern.
         # Optional.
-        # XXX: What happens if the system wants to use an undefined
-        # profile name?  Should we fall back to "default" or just assume
-        # an empty list?
         minimal:
             # A verbose description of the module, optional
             description: Minimal profile installing only the bar package.
             rpms:
                 - bar
         # A set of packages which should be installed into the buildroot of a
-        # module which depends on this module. Specifically, it is used to
+        # module which depends on this module.  Specifically, it is used to
         # flesh out the build group in koji.
         # Optional.
         buildroot:
@@ -117,7 +114,6 @@ data:
                 - bar-extras
     # Module API
     # Optional, defaults to no API.
-    # TODO: Define more API types
     api:
         # The module's public RPM-level API.
         # A list of binary RPM names that are considered to be the
@@ -150,7 +146,9 @@ data:
         # Optional
         rpms:
             # Additional macros that should be defined in the
-            # RPM buildroot, appended to the default set.
+            # RPM buildroot, appended to the default set.  Care should be
+            # taken so that the newlines are preserved.  Literal style
+            # block is recommended, with or without the trailing newline.
             # Optional
             macros: |
                 %demomacro 1
@@ -160,7 +158,6 @@ data:
         # RPM content of the module, optional
         # Keys are the VCS/SRPM names, values dictionaries holding
         # additional information.
-        # TODO: Define architectures to build for
         rpms:
             bar:
                 # Why is this component present.
@@ -189,7 +186,7 @@ data:
                 # xxx is only available on the listed architectures.
                 # Optional, defaults to all available arches.
                 arches: [ i686, x86_64 ]
-                # a list of architectures with multilib
+                # A list of architectures with multilib
                 # installs, i.e. both i686 and x86_64
                 # versions will be installed on x86_64.
                 # Optional, defaults to no multilib.
@@ -211,7 +208,11 @@ data:
         # Module content of this module
         # Included modules are built in the shared buildroot, together with
         # other included content.  Keys are module names, values additional
-        # component information.
+        # component information.  Note this only includes components and their
+        # properties from the referenced module and doesn't inherit any
+        # additional module metadata such as the module's dependencies or
+        # component buildopts.  The included components are built in their
+        # defined buildorder as sub-build groups.
         # Optional
         modules:
             includedmodule: