#31 add Fedora Packaging Guidelines for Modules
Merged 9 months ago by asamalik. Opened 9 months ago by asamalik.
fedora-docs/ asamalik/modularity master  into  master

file modified
+1

@@ -11,6 +11,7 @@ 

  ** xref:making-modules/managing-defaults.adoc[Managing Defaults]

  ** xref:making-modules/inspecting-build-failures.adoc[Inspecting Build Failures]

  ** xref:making-modules/building-modules-locally.adoc[Building Modules Locally]

+ ** xref:making-modules/packaging-guidelines.adoc[Packaging Guidelines]

  ** xref:making-modules/naming-guidelines.adoc[Naming Guidelines]

  * xref:hosting-modules.adoc[Hosting Modules]

  * xref:using-modules.adoc[Using Modules]

@@ -0,0 +1,133 @@ 

+ = Fedora Packaging Guidelines for Modules

+ 

+ These guidelines specify restrictions and guidance for xref:defining-modules.adoc[defining modules in modulemd].

+ 

+ == Short Overview

+ 

+ * Packager **MUST** specify `summary`

+ * Packager **MUST** specify `description`

+ * Packager **MUST** specify `license/module` license(s) based on allowed licenses in Fedora

+ * Packager **MUST** specify `dependencies`

+ * Packager **MUST** specify `components`

+ * Packager **SHOULD** specify `profiles`

+ * Packager **SHOULD** specify `api`

+ * Packager **MAY** specify `data` in key-value format in xmd

+ * Packager **MAY** specify `references`

+ * Packager **MAY** specify `filter`

+ * Packager **MAY** specify `buildopts`

+ * Packager **MUST NOT** specify `name`, name is taken from name of dist-git repository

+ * Packager **MUST NOT** specify `stream`, stream is taken from branch of dist-git repository

+ * Packager **MUST NOT** specify `version`, it is automatically generated by buildsystem

+ * Packager **MUST NOT** specify `arch`, it is automatically filled in by buildsystem

+ * Packager **MUST NOT** specify `servicelevels`, they are automatically filled in by buildsystem from PDC

+ * Packager **MUST NOT** specify `license/content` license(s), they are picked up from components which are built

+ * Packager **MUST NOT** specify `artifacts`

+ 

+ == Long Overview

+ 

+ === Document header and the data block

+ 

+ Every modulemd file **MUST** contain a modulemd document header which consists of the document type tag and the document format version, and a data block holding the module data. 

+ 

+ ----

+ document: modulemd

+ version: 2

+ data:

+     (...)

+ ----

+ 

+ The version is an integer and denotes the version of the metadata format the rest of the document is written in. Packagers **SHOULD** use latest available version of specification. 

+ 

+ === Summary and description

+ 

+ Every module **MUST** include human-readable short summary and description. Both should be written in US English. 

+ 

+ ----

+ summary: An example module

+ description: >-

+     An example long description of an example module, written just

+     to demonstrate the purpose of this field.

+ ----

+ 

+ The summary is a one sentence concise description of the module and **SHOULD NOT** end in a period.

+ 

+ The description expands on this and **SHOULD** end in a period. Description **SHOULD NOT** contain installation instructions or configuration manuals. 

+ 

+ === Licensing

+ 

+ Every module **MUST** contain a license block and declare a list of the module's licenses. Note these aren't the module's components' licenses.

+ 

+ ----

+ license:

+     module:

+         - MIT

+ ----

+ 

+ Fedora content, such as SPEC files or patches not included upstream, uses the MIT license by default, unless the component packager declares otherwise. Therefore MIT might be a reasonable default for most module authors as well.

+ 

+ === Dependencies

+ 

+ Modules **MAY** depend on other modules. These module relationships are listed in the dependencies block. However, none of modules are buildable without `platform` module hence packagers are required to specify it.

+ 

+ Packagers **SHOULD** be using stream name expansion to make their modules compatible with other existing modules. The following example builds and runs the module on any `platform:`

+ 

+ ----

+ dependencies:

+   - buildrequires:

+       platform: []

+     requires:

+       platform: []

+ ----

+ 

+ Note the stream name expansion is only supported by the second version of the format. Unlike in the first version, the `dependencies` block is a list of dictionaries. 

+ 

+ === Extensible module metadata block

+ 

+ Modules **MAY** also contain an extensible metadata block, a list of vendor-defined key-value pairs.

+ 

+ ----

+ xmd:

+     user-defined-key: 42

+     another-user-defined-key:

+         - the first value of the list

+         - the second value of the list

+ ----

+ 

+ === References

+ 

+ Modules **MAY** define links referencing various upstream resources, such as community website, project documentation or upstream bug tracker.

+ 

+ ----

+ references:

+     community: http://www.example.com/

+     documentation: http://www.example.com/docs/1.23/

+     tracker: http://www.example.com/bugs/

+ ----

+ 

+ === Profiles

+ 

+ The module author **MAY** define lists of packages that would be installed when the module is enabled and the particular profile is selected. Whether the packages actually get installed depends on the user's configuration. It is possible to define a profile that doesn't install any packages.

+ 

+ Profile names are arbitrary strings. There are currently few special-purpose profile names defined, see specification for details.

+ 

+ If the module includes one or more profile definition, xref:managing-defaults.adoc[module defaults] **SHOULD** also be defined.

+ 

+ In the case of RPM content, the profile package lists reference binary RPM package names. 

+ 

+ === API

+ 

+ Module API are components, symbols, files or abstract features the module explicitly declares to be its supported interface. Everything else is considered an internal detail and shouldn't be relied on by any other module.

+ 

+ Every module **SHOULD** define its public API. 

+ 

+ === Filters

+ 

+ Module filters define lists of components or other content that should not be part of the resulting, composed module deliverable. They can be used to only ship a limited subset of generated RPM packages, for instance.

+ 

+ ----

+ filter:

+     rpms:

+         - mypackage-plugins

+ ----

+ 

+ Currently the only supported type of filter are binary RPM packages.  

\ No newline at end of file

Migrating this forgotten wiki page into the docs: https://fedoraproject.org/wiki/Module:Guidelines

There are no changes in content, I've just converted it.

I confirm this matches the original page.

We should bring this up to date and integrate it with the rest of the guidelines later.

+1

Pull-Request has been merged by asamalik

9 months ago