From 35eb016fd8fda4c058c101e35c53f640ec5380d4 Mon Sep 17 00:00:00 2001 From: mprahl Date: Jun 24 2019 18:29:58 +0000 Subject: [PATCH 1/2] Move the Rebuild Strategies documentation to a separate file --- diff --git a/README.rst b/README.rst index 8eff63d..0515197 100644 --- a/README.rst +++ b/README.rst @@ -31,6 +31,14 @@ For detailed information on how to contribute, see |docs/CONTRIBUTING.rst|_. .. |docs/CONTRIBUTING.rst| replace:: ``docs/CONTRIBUTING.rst`` .. _docs/CONTRIBUTING.rst: docs/CONTRIBUTING.rst +Rebuild Strategies +================== + +For detailed information on rebuild strategies, see |docs/REBUILD_STRATEGIES.rst|_. + +.. |docs/REBUILD_STRATEGIES.rst| replace:: ``docs/REBUILD_STRATEGIES.rst`` +.. _docs/REBUILD_STRATEGIES.rst: docs/REBUILD_STRATEGIES.rst + Supported build systems ======================= @@ -130,70 +138,6 @@ Options: rebuilt). For the available options, please look at the "Rebuild Strategies" section below. -Rebuild Strategies ------------------- - -To view the available/allowed rebuild strategies on your MBS instance, query the rebuild-strategies -API. - -:: - - GET /module-build-service/1/rebuild-strategies/ - -:: - - HTTP 200 OK - -:: - - { - "items": [ - { - "allowed": false, - "default": false, - "description": "All components will be rebuilt", - "name": "all" - }, - { - "allowed": true, - "default": true, - "description": "All components that have changed and those in subsequent batches will be rebuilt", - "name": "changed-and-after" - }, - { - "allowed": false, - "default": false, - "description": "All changed components will be rebuilt", - "name": "only-changed" - } - ] - } - - -As described in the API, the following rebuild strategies are supported in MBS: - -- ``all`` - all components will be rebuilt. This means that even if the components have not changed - since the previous build of the module, all components will be rebuilt and not reused. -- ``changed-and-after`` - all components that have changed and those in subsequent batches will be - rebuilt. Take for example a module with two batches, and each batch has two components. If one of - the two components in the first batch is changed, the other component in the batch will be reused - while all other components in the module will be rebuilt. By default, MBS only allows this - rebuild strategy. -- ``only-changed`` - all changed components will be rebuilt. This means that all components, - regardless of what happened in previous batches, will be reused if they haven't been changed. - This strategy is a compromise between ``all`` and ``changed-and-after``. - -To configure the rebuild strategies in MBS, you may configure the following options: - -- ``rebuild_strategy`` - a string of the rebuild strategy to use by default. This defaults to - ``changed-and-after``. -- ``rebuild_strategy_allow_override`` - a boolean that determines if a user is allowed to specify - the rebuild strategy they want to use when submitting a module build. This defaults to ``False``. -- ``rebuild_strategies_allowed`` - a list of rebuild strategies that are allowed to be used. This - only takes effect if ``rebuild_strategy_allow_override`` is set to ``True``. This defaults to - allowing all rebuild strategies that MBS supports. - - Module build state query ------------------------ diff --git a/docs/REBUILD_STRATEGIES.rst b/docs/REBUILD_STRATEGIES.rst new file mode 100644 index 0000000..642f543 --- /dev/null +++ b/docs/REBUILD_STRATEGIES.rst @@ -0,0 +1,62 @@ +Rebuild Strategies +================== + +To view the available/allowed rebuild strategies on your MBS instance, query the rebuild-strategies +API. + +:: + + GET /module-build-service/1/rebuild-strategies/ + +:: + + HTTP 200 OK + +:: + + { + "items": [ + { + "allowed": false, + "default": false, + "description": "All components will be rebuilt", + "name": "all" + }, + { + "allowed": true, + "default": true, + "description": "All components that have changed and those in subsequent batches will be rebuilt", + "name": "changed-and-after" + }, + { + "allowed": false, + "default": false, + "description": "All changed components will be rebuilt", + "name": "only-changed" + } + ] + } + + +As described in the API, the following rebuild strategies are supported in MBS: + +- ``all`` - all components will be rebuilt. This means that even if the components have not changed + since the previous build of the module, all components will be rebuilt and not reused. +- ``changed-and-after`` - all components that have changed and those in subsequent batches will be + rebuilt. Take for example a module with two batches, and each batch has two components. If one of + the two components in the first batch is changed, the other component in the batch will be reused + while all other components in the module will be rebuilt. By default, MBS only allows this + rebuild strategy. +- ``only-changed`` - all changed components will be rebuilt. This means that all components, + regardless of what happened in previous batches, will be reused if they haven't been changed. + This strategy is a compromise between ``all`` and ``changed-and-after``. + +To configure the rebuild strategies in MBS, you may configure the following options: + +- ``rebuild_strategy`` - a string of the rebuild strategy to use by default. This defaults to + ``changed-and-after``. +- ``rebuild_strategy_allow_override`` - a boolean that determines if a user is allowed to specify + the rebuild strategy they want to use when submitting a module build. This defaults to ``False``. +- ``rebuild_strategies_allowed`` - a list of rebuild strategies that are allowed to be used. This + only takes effect if ``rebuild_strategy_allow_override`` is set to ``True``. This defaults to + allowing all rebuild strategies that MBS supports. From c887448a7ca9af4604c7cd317e37245bae317fc8 Mon Sep 17 00:00:00 2001 From: mprahl Date: Jun 25 2019 14:19:23 +0000 Subject: [PATCH 2/2] Add additional documentation about rebuild strategies --- diff --git a/docs/REBUILD_STRATEGIES.rst b/docs/REBUILD_STRATEGIES.rst index 642f543..c542e1c 100644 --- a/docs/REBUILD_STRATEGIES.rst +++ b/docs/REBUILD_STRATEGIES.rst @@ -1,8 +1,14 @@ Rebuild Strategies ================== -To view the available/allowed rebuild strategies on your MBS instance, query the rebuild-strategies -API. +MBS has the concept of rebuild strategies, which influence which components can be reused from a +previous module build. This only affects MBS deployments that use Koji as the builder. + +Support Rebuild Strategies +========================== + +To view the available and allowed rebuild strategies on an MBS instance, query the +rebuild-strategies API endpoint. :: @@ -38,18 +44,8 @@ API. } -As described in the API, the following rebuild strategies are supported in MBS: - -- ``all`` - all components will be rebuilt. This means that even if the components have not changed - since the previous build of the module, all components will be rebuilt and not reused. -- ``changed-and-after`` - all components that have changed and those in subsequent batches will be - rebuilt. Take for example a module with two batches, and each batch has two components. If one of - the two components in the first batch is changed, the other component in the batch will be reused - while all other components in the module will be rebuilt. By default, MBS only allows this - rebuild strategy. -- ``only-changed`` - all changed components will be rebuilt. This means that all components, - regardless of what happened in previous batches, will be reused if they haven't been changed. - This strategy is a compromise between ``all`` and ``changed-and-after``. +System Configuration +==================== To configure the rebuild strategies in MBS, you may configure the following options: @@ -60,3 +56,68 @@ To configure the rebuild strategies in MBS, you may configure the following opti - ``rebuild_strategies_allowed`` - a list of rebuild strategies that are allowed to be used. This only takes effect if ``rebuild_strategy_allow_override`` is set to ``True``. This defaults to allowing all rebuild strategies that MBS supports. + + +How MBS Finds a Compatible Module +================================= + +MBS finds a compatible module to reuse components from by searching its database for the last built +module with the following requirements: + +- The module name is the same as the module being built +- The module stream is the same as the module being built +- The module is in the ``ready`` state (this inherently ignores scratch builds) +- The expanded buildrequires section (after Module Stream Expansion) has the same name:stream + entries as the module being built +- The module must have been built from a modulemd stored in source control (most deployments only + allow this) + +Additionally, if the rebuild strategy for the module being built is ``changed-and-after``, then the +module to reuse components from will have a rebuild strategy of ``changed-and-after`` or ``all``. + + +How the Rebuild Strategies Work +=============================== + +all +--- + +No components will be reused. This is used to completely rebuild a module. + + +changed-and-after +----------------- + +All components that have changed and those in subsequent batches will be rebuilt. This is a +conservative middle ground between ``all`` and ``only-changed``. + +The following characteristics of the compatible module must be true for a component to be reused: + +- The ``buildopts.rpms.macros`` field of the module being built must match the compatible module +- All the components in the module being built must have also been built in the compatible module +- All the arches of the components in the module being built must match the components in the + compatible module + +The following characteristics of the component must be true for it to be reused: + +- The ref has to match the one being built +- The batch has to match the one being built +- The previous batches of the module build must have the same exact components and component refs + + +only-changed +------------ + +All changed components will be rebuilt. This means that all components, regardless of what happened +in previous batches, will be reused if they haven't changed. + +The following characteristics of the compatible module must be true for a component to be reused +(this will be changed after #1298): + +- All the components in the module being built must have also been built in the compatible module +- All the arches of the components in the module being built must match the components in the + compatible module + +The following characteristics of the component must be true for it to be reused: + +- The ref has to match the one being built