From 4b3235cd5799035fd481ea08ca63ac6c61614ca2 Mon Sep 17 00:00:00 2001
From: Tomas Tomecek <ttomecek@redhat.com>
Date: Aug 04 2017 11:52:22 +0000
Subject: improve developing modulemd section


Signed-off-by: Tomas Tomecek <ttomecek@redhat.com>

---

diff --git a/source/development/building-modules/developing.rst b/source/development/building-modules/developing.rst
index 6591045..fe784a8 100644
--- a/source/development/building-modules/developing.rst
+++ b/source/development/building-modules/developing.rst
@@ -3,9 +3,9 @@ Defining modules in modulemd
 
 To have your module build, you need to start with writing a `modulemd
 <https://pagure.io/modulemd>`__ file which is a definition of your module
-including the components, API, and all the information necessary to build
-your module like specifying build dependencies and a build order for the
-packages. Let’s have a look at an example Vim module:
+including the components, dependencies, API, and more. The information
+necessary to build your module is: build dependencies, source and build order
+for the packages. Let’s have a look at an example Vim module:
 
 ::
 
@@ -18,9 +18,9 @@ packages. Let’s have a look at an example Vim module:
             module: [ MIT ]
         dependencies:
             buildrequires:
-                base_runtime: master
+                base-runtime: f26
             requires:
-                base_runtime: master
+                base-runtime: f26
         references:
             community: http://www.vim.org/
             documentation: http://www.vim.org/docs.php
@@ -41,20 +41,20 @@ packages. Let’s have a look at an example Vim module:
             rpms:
                 vim:
                     rationale: Provides API for this module
-                    ref: f25
+                    ref: f26
                     buildorder: 10
                 generic-release:
                     rationale: build dependency
-                    ref: f25
+                    ref: f26
                 perl-Carp:
                     rationale: build dependency
-                    ref: f25
+                    ref: f26
                 gpm:
                     rationale: build dependency
-                    ref: f25
+                    ref: f26
                 perl-Exporter:
                     rationale: build dependency
-                    ref: f25
+                    ref: f26
 
 Notice that there is no information about the name or version of the module.
 That’s because the build system takes this information from the git
@@ -65,19 +65,72 @@ repository, from which the module is build:
 * Commit timestamp == module version
 
 All dependencies of vim need to be listed under components/rpms, except
-those that are already included in `Base Runtime
-<https://raw.githubusercontent.com/asamalik/fake-base-runtime-module-image/master/packages/gen-core-binary-pkgs.txt>`__.
-Here's how you can get the list of vim dependencies that are not in Base
-Runtime:
+those that are already included in other modules, such as `Base Runtime
+<http://pkgs.fedoraproject.org/cgit/modules/base-runtime.git/tree/base-runtime.yaml>`__.
+
+At the moment there is no service which tracks which packages are present in
+which modules. In the meantime, `we've developed a tool
+<https://pagure.io/modularity/modularity-tools>`__ which is able to construct a
+preliminary modulemd file for a selected set of rpms you provide. It queries
+information about previously built modules to fulfill build and runtime package
+dependencies.
 
 ::
 
-    wget https://raw.githubusercontent.com/asamalik/fake-base-runtime-module-image/master/packages/gen-core-binary-pkgs.txt
-    for i in `repoquery --requires --recursive --resolve --qf "%{SOURCERPM}\n" \
-      vim-enhanced vim-minimal vim-common vim-filesystem \
-      | sed -e "s/-[^-]*-[^-]*$//" | sort -n | uniq` ; do
-      grep -wq $i gen-core-binary-pkgs.txt || echo $i
-    done
+    $ mod-tools rpm2module nodejs npm
+    $ cat *.yaml
+    data:
+      api:
+        rpms: [nodejs, npm]
+      components:
+        rpms:
+          http-parser: {rationale: Build and runtime dependency.}
+          nodejs: {buildorder: 10, rationale: Runtime dependency.}
+      dependencies:
+        buildrequires: {base-runtime: f26, shared-userspace: f26}
+        requires: {base-runtime: f26, shared-userspace: f26}
+      description: ''
+      license:
+        module: [MIT]
+      summary: ''
+    document: modulemd
+    version: 1
+
+You can also use `depchase <https://github.com/fedora-modularity/depchase>`__
+to identify precise build and runtime dependencies of your packages. Please
+consult the documentation of the tool for more information.
+
+
+Bootstrapping
+-------------
+
+It may happen that some build requirements are missing for your package to
+build in a module. There are two solutions:
+
+1. Create a new bootstrap module which helps bootstrapping your target module.
+   The bootstrap module will probably refer to a commit in dist-git rpm where
+   the package enables bootstrapping (cutting build dependencies down,
+   disabling features). For more info, see `this module
+   <http://pkgs.fedoraproject.org/cgit/modules/common-build-dependencies-bootstrap.git/tree/common-build-dependencies-bootstrap.yaml?h=f26>`__.
+
+2. Tag existing packages from koji into the module build tag so they are
+   present during build. This solution isn't preferred because it makes it at
+   least very hard if not impossible to reproduce how a module was built at a
+   later point.
+
+
+Module API
+----------
+
+There are two important concepts you need to have in your module:
+
+1. **API** — list of binary packages which are provided by the module and supported
+2. **filter** — list of binary packages which should not be provided by the
+   module (should be filtered out during the compose phase). These are usually
+   packages which are used to build the target packages and the maintainer
+   doesn't want to support them. They can also be subpackages of target
+   packages which can't be installed due to missing runtime dependencies.
+
 
 Check the syntax
 ----------------