diff --git a/yaml_specs/modulemd_packager_v2.yaml b/yaml_specs/modulemd_packager_v2.yaml index 026c83654..ab5e2d79d 100644 --- a/yaml_specs/modulemd_packager_v2.yaml +++ b/yaml_specs/modulemd_packager_v2.yaml @@ -3,15 +3,18 @@ # for a module stream. It is always a proper subset of a `document: modulemd` # of the same `version`. document: modulemd-packager + # Module metadata format version version: 2 data: # A short summary describing the module, required summary: An example module + # A verbose description of the module, required description: >- A module for the demonstration of the metadata format. Also, the obligatory lorem ipsum dolor sit amet goes right here. + # Module and content licenses in the Fedora license identifier # format, required license: @@ -21,6 +24,7 @@ data: # module. module: - MIT + # Module dependencies, if any. Optional. # A list of dictionaries describing build and runtime dependencies # of this module. Each list item describes a combination of dependencies @@ -36,8 +40,6 @@ data: # the runtime block so that it matches the stream the module was built # against. Multiple builds result in multiple output modulemd files. # See below for an example. - # TODO: Provides, conflicts, obsoletes, recommends, etc. - # Do we even need those? # The example below illustrates how to build the same module in four # different ways, with varying build time and runtime dependencies. dependencies: @@ -48,6 +50,7 @@ data: platform: [-f27, -f28, -epel7] requires: platform: [-f27, -f28, -epel7] + # For platform:f27 perform two builds, one with buildtools:v1, another # with buildtools:v2 in the buildroot. Both will also utilize # compatible:v3. At runtime, buildtools isn't required and either @@ -59,6 +62,7 @@ data: requires: platform: [f27] compatible: [v3, v4] + # For platform:f28 builds, require either runtime:a or runtime:b at # runtime. Only one build is performed. - buildrequires: @@ -66,6 +70,7 @@ data: requires: platform: [f28] runtime: [a, b] + # For platform:epel7, build against against all available extras # streams and moreextras:foo and moreextras:bar. The number of builds # in this case will be 2 * <the number of extras streams available>. @@ -79,14 +84,18 @@ data: platform: [epel7] extras: [] moreextras: [foo, bar] + # References to external resources, typically upstream, optional references: # Upstream community website, if it exists, optional community: http://www.example.com/ + # Upstream documentation, if it exists, optional documentation: http://www.example.com/ + # Upstream bug tracker, if it exists, optional tracker: http://www.example.com/ + # Profiles define the end user's use cases for the module. They consist of # package lists of components to be installed by default if the module is # enabled. The keys are the profile names and contain package lists by @@ -104,6 +113,7 @@ data: - bar - bar-extras - baz + # Defines a set of packages which are meant to be installed inside # container image artifact. # Optional. @@ -111,6 +121,7 @@ data: rpms: - bar - bar-devel + # This profile provides minimal set of packages providing functionality # of this module. This is meant to be used on target systems where size # of the distribution is a real concern. @@ -120,6 +131,7 @@ data: 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 # flesh out the build group in koji. @@ -127,6 +139,7 @@ data: buildroot: rpms: - bar-devel + # Very similar to the buildroot profile above, this is used by the # build system to specify any additional packages which should be # installed during the buildSRPMfromSCM step in koji. @@ -134,6 +147,7 @@ data: srpm-buildroot: rpms: - bar-extras + # Module API # Optional, defaults to no API. api: @@ -151,6 +165,7 @@ data: - bar-devel - baz - xxx + # Module component filters # Optional, defaults to no filters. filter: @@ -160,6 +175,7 @@ data: # Optional, defaults to an empty list. rpms: - baz-nonfoo + # Functional components of the module, optional components: # RPM content of the module, optional @@ -172,30 +188,36 @@ data: # bootstrapping ref before building the package for real. # Optional name: bar-real + # Why is this component present. # A simple, free-form string. # Required. rationale: We need this to demonstrate stuff. + # Use this repository if it's different from the build # system configuration. # Optional. repository: https://pagure.io/bar.git + # Use this lookaside cache if it's different from the # build system configuration. # Optional. cache: https://example.com/cache + # Use this specific commit hash, branch name or tag for # the build. If ref is a branch name, the branch HEAD # will be used. If no ref is given, the master branch # is assumed. # Optional. ref: 26ca0c0 + # Use the "buildafter" value to specify that this component # must be be ordered later than some other entries in this map. # The values of this array come from the keys of this map and # not the real component name to enable bootstrapping. buildafter: - baz + # If buildroot is set to True, the packages listed in this # module's buildroot profile will be installed into the # buildroot of any component built in subsequent @@ -203,22 +225,27 @@ data: # explicitly include these packages in its BuildRequires. # Optional. Defaults to "false" if not specified. buildroot: false + # If srpm-buildroot is set to True, the packages listed in this # module's srpm-buildroot profile will be installed into the # buildroot when performing the buildSRPMfromSCM step in # subsequent buildafter batches. # Optional. Defaults to "false" if not specified. srpm-buildroot: false + # baz has no extra options baz: rationale: This one is here to demonstrate other stuff. + xxx: rationale: xxx demonstrates arches and multilib. + # xxx is only available on the listed architectures. # Includes specific hardware architectures, not families. # See the data.arch field for details. # Optional, defaults to all available arches. arches: [i686, x86_64] + # A list of architectures with multilib # installs, i.e. both i686 and x86_64 # versions will be installed on x86_64. @@ -226,14 +253,17 @@ data: # See the data.arch field for details. # Optional, defaults to no multilib. multilib: [x86_64] + # This package requires a particular version of 'xyz' to be # present in order to build correctly, so we inform the build # system not to build this until 'xyz' has completed # successfully. buildafter: - xyz + xyz: rationale: xyz is a bundled dependency of xxx. + # Module content of this module # Included modules are built in the shared buildroot, together with # other included content. Keys are module names, values additional @@ -247,9 +277,11 @@ data: # Why is this module included? # Required rationale: Included in the stack, just because. + # Link to VCS repository that contains the modulemd file # if it differs from the buildsystem default configuration. # Optional. repository: https://pagure.io/includedmodule.git + # See the rpms ref. ref: somecoolbranchname diff --git a/yaml_specs/modulemd_stream_v2.yaml b/yaml_specs/modulemd_stream_v2.yaml index 93c1f1355..48548462a 100644 --- a/yaml_specs/modulemd_stream_v2.yaml +++ b/yaml_specs/modulemd_stream_v2.yaml @@ -1,50 +1,125 @@ +############################################################################## +# Glossary: # +# # +# build system: The process by which a module is built and packaged. In many # +# cases, this will be the Module Build Service tool, but this term is used # +# as a catch-all to describe any mechanism for producing a yum repository # +# containing modular content from input module metadata files. # +# # +# # +# == Attribute Types == # +# # +# MANDATORY: Attributes of this type must be filled in by the packager of # +# this module. They must also be preserved and provided in the output # +# metadata produced by the build system for inclusion into a repository. # +# # +# OPTIONAL: Attributes of this type may be provided by the packager of this # +# module, when appropriate. If they are provided, they must also be # +# preserved and provided in the output metadata produced by the build # +# system for inclusion into a repository. # +# # +# AUTOMATIC: Attributes of this type must be present in the the repository # +# metadata, but they may be left unspecified by the packager. In this case, # +# the build system is responsible for generating an appropriate value for # +# the attribute and including it in the repository metadata. If the packager # +# specifies this attribute explicitly, it must be preserved and provided in # +# the output metadata for inclusion into a repository. # +############################################################################## + + # Document type identifier # `document: modulemd` describes the contents of a module stream document: modulemd # Module metadata format version version: 2 data: - # Module name, optional - # Typically filled in by the buildsystem, using the VCS repository - # name as the name of the module. + # name: + # The name of the module + # Filled in by the build system, using the VCS repository name as the name + # of the module. + # + # Type: AUTOMATIC + # + # Mandatory for module metadata in a yum/dnf repository. name: foo - # Module update stream, optional - # Typically filled in by the buildsystem, using the VCS branch name - # as the name of the stream. + + # stream: + # Module update stream + # Filled in by the buildsystem, using the VCS branch name as the name of + # the stream. + # + # Type: AUTOMATIC + # + # Mandatory for module metadata in a yum/dnf repository. stream: latest - # Module version, integer, optional, cannot be negative - # Typically filled in by the buildsystem, using the VCS commit - # timestamp. Module version defines upgrade path for the particular - # update stream. + + # version: + # Module version, integer, cannot be negative + # Filled in by the buildsystem, using the VCS commit timestamp. Module + # version defines upgrade path for the particular update stream. + # + # Type: AUTOMATIC + # + # Mandatory for module metadata in a yum/dnf repository. version: 20160927144203 - # Module context flag, optional + + # context: + # Module context flag # The context flag serves to distinguish module builds with the # same name, stream and version and plays an important role in # future automatic module stream name expansion. # Filled in by the buildsystem. A short hash of the module's name, - # stream, version and its expanded runtime dependencies. + # stream, version and its expanded runtime dependencies. The exact + # mechanism of generating the has is unspecified except that it must be + # stable. + # + # Type: AUTOMATIC + # + # Mandatory for module metadata in a yum/dnf repository. context: c0ffee43 - # Module artifact architecture, optional + + # arch: + # Module artifact architecture # Contains a string describing the module's artifacts' main hardware # architecture compatibility, distinguishing the module artifact, # e.g. a repository, from others with the same name, stream, version and # context. This is not a generic hardware family (i.e. basearch). # Examples: i386, i486, armv7hl, x86_64 # Filled in by the buildsystem during the compose stage. + # + # Type: AUTOMATIC + # + # Mandatory for module metadata in a yum/dnf repository. arch: x86_64 - # A short summary describing the module, required + + # Summary: + # A short summary describing the module + # + # Type: MANDATORY + # + # Mandatory for module metadata in a yum/dnf repository. summary: An example module - # A verbose description of the module, required + + # description: + # A verbose description of the module + # + # Type: MANDATORY + # + # Mandatory for module metadata in a yum/dnf repository. description: >- A module for the demonstration of the metadata format. Also, the obligatory lorem ipsum dolor sit amet goes right here. - # Service levels, optional + + # servicelevels: + # Service levels # This is a dictionary of important dates (and possibly supplementary data # in the future) that describes the end point of certain functionality, # such as the date when the module will transition to "security fixes only" # or go completely end-of-life. # Filled in by the buildsystem. Service level names might have special # meaning to other systems. Defined externally. + # + # Type: AUTOMATIC servicelevels: rawhide: # EOL dates are the ISO 8601 format. @@ -55,28 +130,47 @@ data: eol: 2077-10-23 security_fixes: eol: 2077-10-23 + + # license: # Module and content licenses in the Fedora license identifier - # format, required + # format + # + # Type: MANDATORY license: - # Module license, required + # module: + # Module license # This list covers licenses used for the module metadata and # possibly other files involved in the creation of this specific # module. + # + # Type: MANDATORY module: - MIT - # Content license, optional + + # content: + # Content license # A list of licenses used by the packages in the module. # This should be populated by build tools, not the module author. + # + # Type: AUTOMATIC + # + # Mandatory for module metadata in a yum/dnf repository. content: - Beerware - GPLv2+ - zlib + + # xmd: # Extensible metadata block # A dictionary of user-defined keys and values. - # Optional. Defaults to an empty dictionary. + # Defaults to an empty dictionary. + # + # Type: OPTIONAL xmd: some_key: some_data - # Module dependencies, if any. Optional. + + # dependencies: + # Module dependencies, if any # A list of dictionaries describing build and runtime dependencies # of this module. Each list item describes a combination of dependencies # this module can be built or run against. @@ -91,10 +185,10 @@ data: # the runtime block so that it matches the stream the module was built # against. Multiple builds result in multiple output modulemd files. # See below for an example. - # TODO: Provides, conflicts, obsoletes, recommends, etc. - # Do we even need those? # The example below illustrates how to build the same module in four # different ways, with varying build time and runtime dependencies. + # + # Type: OPTIONAL dependencies: # Build on all available platforms except for f27, f28 and epel7 # After build, the runtime dependency will match the one used for @@ -103,6 +197,7 @@ data: platform: [-f27, -f28, -epel7] requires: platform: [-f27, -f28, -epel7] + # For platform:f27 perform two builds, one with buildtools:v1, another # with buildtools:v2 in the buildroot. Both will also utilize # compatible:v3. At runtime, buildtools isn't required and either @@ -114,6 +209,7 @@ data: requires: platform: [f27] compatible: [v3, v4] + # For platform:f28 builds, require either runtime:a or runtime:b at # runtime. Only one build is performed. - buildrequires: @@ -121,6 +217,7 @@ data: requires: platform: [f28] runtime: [a, b] + # For platform:epel7, build against against all available extras # streams and moreextras:foo and moreextras:bar. The number of builds # in this case will be 2 * <the number of extras streams available>. @@ -134,14 +231,31 @@ data: platform: [epel7] extras: [] moreextras: [foo, bar] - # References to external resources, typically upstream, optional + + # references: + # References to external resources, typically upstream + # + # Type: OPTIONAL references: - # Upstream community website, if it exists, optional + # community: + # Upstream community website, if it exists + # + # Type: OPTIONAL community: http://www.example.com/ - # Upstream documentation, if it exists, optional + + # documentation: + # Upstream documentation, if it exists + # + # Type: OPTIONAL documentation: http://www.example.com/ - # Upstream bug tracker, if it exists, optional + + # tracker: + # Upstream bug tracker, if it exists + # + # Type: OPTIONAL tracker: http://www.example.com/ + + # profiles: # Profiles define the end user's use cases for the module. They consist of # package lists of components to be installed by default if the module is # enabled. The keys are the profile names and contain package lists by @@ -150,48 +264,65 @@ data: # module. Then users are able to install packages on their own. If they # select a specific profile, the package manager should install all # packages of that profile. - # Optional, defaults to no profile definitions. + # Defaults to no profile definitions. + # + # Type: OPTIONAL profiles: # The default profile, used unless any other profile was selected. - # Optional, defaults to empty lists. + # Defaults to empty lists. + # + # Type: OPTIONAL default: rpms: - bar - bar-extras - baz + # Defines a set of packages which are meant to be installed inside # container image artifact. - # Optional. + # + # Type: OPTIONAL container: rpms: - bar - bar-devel + # This profile provides minimal set of packages providing functionality # of this module. This is meant to be used on target systems where size # of the distribution is a real concern. - # Optional. + # + # Type: Optional 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 # flesh out the build group in koji. - # Optional. + # + # Type: OPTIONAL buildroot: rpms: - bar-devel + # Very similar to the buildroot profile above, this is used by the # build system to specify any additional packages which should be # installed during the buildSRPMfromSCM step in koji. - # Optional. + # + # Type: OPTIONAL srpm-buildroot: rpms: - bar-extras + + # api: # Module API - # Optional, defaults to no API. + # Defaults to no API. + # + # Type: OPTIONAL api: + # rpms: # The module's public RPM-level API. # A list of binary RPM names that are considered to be the # main and stable feature of the module; binary RPMs not listed @@ -199,117 +330,180 @@ data: # In the example here we don't list the xyz package as it's only # included as a dependency of xxx. However, we list a subpackage # of bar, bar-extras. - # Optional, defaults to an empty list. + # Defaults to an empty list. + # + # Type: OPTIONAL rpms: - bar - bar-extras - bar-devel - baz - xxx + + # filter: # Module component filters - # Optional, defaults to no filters. + # Defaults to no filters. + # + # Type: OPTIONAL filter: + # rpms: # RPM names not to be included in the module. # By default, all built binary RPMs are included. In the example # we exclude a subpackage of bar, bar-nonfoo from our module. - # Optional, defaults to an empty list. + # Defaults to an empty list. + # + # Type: OPTIONAL rpms: - baz-nonfoo + + # buildopts: # Component build options # Additional per component type module-wide build options. - # Optional + # + # Type: OPTIONAL buildopts: + # rpms: # RPM-specific build options - # Optional + # + # Type: OPTIONAL rpms: + # macros: # Additional macros that should be defined in the # 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 + # + # Type: OPTIONAL macros: | %demomacro 1 %demomacro2 %{demomacro}23 + + # whitelist: # Explicit list of package build names this module will produce. # By default the build system only allows components listed under # data.components.rpms to be built as part of this module. # In case the expected RPM build names do not match the component # names, the list can be defined here. # This list overrides rather then just extends the default. - # Optional, list of package build names without versions. + # List of package build names without versions. + # + # Type: OPTIONAL whitelist: - fooscl-1-bar - fooscl-1-baz - xxx - xyz + + # arches: # Instructs the build system to only build the # module on this specific set of architectures. # Includes specific hardware architectures, not families. # See the data.arch field for details. - # Optional, defaults to all available arches. + # Defaults to all available arches. + # + # Type: OPTIONAL arches: [i686, x86_64] - # Functional components of the module, optional + + # components: + # Functional components of the module + # + # Type: OPTIONAL components: - # RPM content of the module, optional + # rpms: + # RPM content of the module # Keys are the VCS/SRPM names, values dictionaries holding # additional information. + # + # Type: OPTIONAL rpms: bar: + # name: # The real name of the package, if it differs from the key in # this dictionary. Used when bootstrapping to build a # bootstrapping ref before building the package for real. - # Optional + # + # Type: OPTIONAL name: bar-real + + # rationale: # Why is this component present. # A simple, free-form string. - # Required. + # + # Type: MANDATORY rationale: We need this to demonstrate stuff. + + # repository: # Use this repository if it's different from the build # system configuration. - # Optional. + # + # Type: AUTOMATIC repository: https://pagure.io/bar.git + + # cache: # Use this lookaside cache if it's different from the # build system configuration. - # Optional. + # + # Type: AUTOMATIC cache: https://example.com/cache + + # ref: # Use this specific commit hash, branch name or tag for # the build. If ref is a branch name, the branch HEAD # will be used. If no ref is given, the master branch # is assumed. - # Optional. + # + # Type: AUTOMATIC ref: 26ca0c0 + + # buildafter: # Use the "buildafter" value to specify that this component # must be be ordered later than some other entries in this map. # The values of this array come from the keys of this map and # not the real component name to enable bootstrapping. # Use of both buildafter and buildorder in the same document is # prohibited, as they will conflict. + # + # + # Type: AUTOMATIC # buildafter: # - baz + + # buildonly: # Use the "buildonly" value to indicate that all artifacts # produced by this component are intended only for building # this component and should be automatically added to the # data.filter.rpms list after the build is complete. - # Optional. Defaults to "false" if not specified. + # Defaults to "false" if not specified. + # + # Type: AUTOMATIC buildonly: false + # If buildroot is set to True, the packages listed in this # module's buildroot profile will be installed into the # buildroot of any component built in subsequent # buildorder/buildafter batches, even if that module does not # explicitly include these packages in its BuildRequires. - # Optional. Defaults to "false" if not specified. + # Defaults to "false" if not specified. + # + # Type: OPTIONAL buildroot: false + # If srpm-buildroot is set to True, the packages listed in this # module's srpm-buildroot profile will be installed into the # buildroot when performing the buildSRPMfromSCM step in # subsequent buildorder/buildafter batches. - # Optional. Defaults to "false" if not specified. + # Defaults to "false" if not specified. + # Type: OPTIONAL srpm-buildroot: false + # baz has no extra options baz: rationale: This one is here to demonstrate other stuff. + xxx: rationale: xxx demonstrates arches and multilib. + + # arches: # xxx is only available on the listed architectures. # Includes specific hardware architectures, not families. # See the data.arch field for details. @@ -317,31 +511,44 @@ data: # component on this specific set of architectures. # If data.buildopts.arches is also specified, # this must be a subset of those architectures. - # Optional, defaults to all available arches. + # Defaults to all available arches. + # + # Type: AUTOMATIC arches: [i686, x86_64] + + # multilib # A list of architectures with multilib # installs, i.e. both i686 and x86_64 # versions will be installed on x86_64. # Includes specific hardware architectures, not families. # See the data.arch field for details. - # Optional, defaults to no multilib. + # Defaults to no multilib. + # + # Type: AUTOMATIC multilib: [x86_64] + xyz: rationale: xyz is a bundled dependency of xxx. + + # buildorder: # Build order group # When building, components are sorted by build order tag # and built in batches grouped by their buildorder value. # Built batches are then re-tagged into the buildroot. # Multiple components can have the same buildorder index # to map them into build groups. - # Optional, defaults to zero. + # Defaults to zero. # Integer, negative values are allowed. # In this example, bar, baz and xxx are built first in # no particular order, then tagged into the buildroot, # then, finally, xyz is built. # Use of both buildafter and buildorder in the same document is # prohibited, as they will conflict. + # + # Type: OPTIONAL buildorder: 10 + + # modules: # Module content of this module # Included modules are built in the shared buildroot, together with # other included content. Keys are module names, values additional @@ -350,29 +557,49 @@ data: # 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 + # + # Type: OPTIONAL modules: includedmodule: + + # rationale: # Why is this module included? - # Required + # + # Type: MANDATORY rationale: Included in the stack, just because. + # Link to VCS repository that contains the modulemd file # if it differs from the buildsystem default configuration. - # Optional. + # + # Type: AUTOMATIC repository: https://pagure.io/includedmodule.git + + # ref: # See the rpms ref. + # + # Type: AUTOMATIC ref: somecoolbranchname + + # buildorder # See the rpms buildorder. + # + # Type: AUTOMATIC buildorder: 100 + + # artifacts: # Artifacts shipped with this module # This section lists binary artifacts shipped with the module, allowing # software management tools to handle module bundles. This section is # populated by the module build system. - # Optional + # + # Type: AUTOMATIC artifacts: + + # rpms: # RPM artifacts shipped with this module # A set of NEVRAs associated with this module. - # Optional + # + # Type: AUTOMATIC rpms: - bar-0:1.23-1.module_deadbeef.x86_64 - bar-devel-0:1.23-1.module_deadbeef.x86_64 @@ -381,24 +608,50 @@ data: - xxx-0:1-1.module_deadbeef.x86_64 - xxx-0:1-1.module_deadbeef.i686 - xyz-0:1-1.module_deadbeef.x86_64 + # The rpm-map exists to link checksums from repomd to specific # artifacts produced by this module. Any item in this list must match # an entry in the data.artifacts.rpms section. - # Optional. + # + # Type: AUTOMATIC rpm-map: - # The digest-type of this checksum. Required. + + # The digest-type of this checksum. + # + # Type: MANDATORY sha256: - # The checksum of the artifact being sought. Required. + + # The checksum of the artifact being sought. + # + # Type: MANDATORY ee47083ed80146eb2c84e9a94d0836393912185dcda62b9d93ee0c2ea5dc795b: - # The RPM name. Required. + + # The RPM name. + # + # Type: Mandatory name: bar - # The RPM epoch. Required. + + # The RPM epoch. + # + # Type: OPTIONAL epoch: 0 - # The RPM version. Required. + + # The RPM version. + # + # Type: MANDATORY version: 1.23 - # The RPM release. Required. + + # The RPM release. + # + # Type: MANDATORY release: 1.module_deadbeef - # The RPM architecture. Required. + + # The RPM architecture. + # + # Type: MANDATORY arch: x86_64 - # The complete RPM NEVRA. Required. + + # The complete RPM NEVRA. + # + # Type: MANDATORY nevra: bar-0:1.23-1.module_deadbeef.x86_64