From c23b18683145eefb611a13dc3d7a45d0dda884e7 Mon Sep 17 00:00:00 2001 From: Dave Jones Date: Wed, 19 Jun 2024 11:58:16 +0100 Subject: [PATCH] Replace plainbox references (Infra) (#1285) * Replace definition of plainbox Given there's inevitably still some references to plainbox left in the docs (mostly in identifiers), I think it makes sense to leave this definition here but to make clear the term is obsolete * Replace plainbox with checkbox This covers all the trivial replacements in the docs. Subsequent commits deal with the more complex cases * Remove references to ancient plainbox versions Given that the version referenced is 0.24, released in 2015, rather than try and map these to the checkbox versions they were first incorporated within I suspect it's better to simply remove the reference to plainbox entirely as the described behaviour is presumably present in every version of checkbox encountered today. * Replace "plainbox-provider-snappy" with "base" I can find no other references to plainbox-provider-snappy, and the units referenced in the examples below are now part of the "base" provider. * Remove reference to cleanup.sh It doesn't appear to exist and just causes an error (tested with various base= options and none generated a cleanup.sh) * Correct path The checkbox-provider-myproject path *does* exist, but only under the checkbox-myproject path and there's no explicit instruction to enter it. * Remove reference to the plainbox command There doesn't appear to be an equivalent checkbox flag that the reference could be replaced with? * Replace man-page refs with doc links The man-pages do not exist (checkbox is distributed as a snap), and I suspect these references are better dealt with by linking to the reference docs * Quote "checkbox" This is referring to an actual snap name, rather than the project itself. * Capitalize references to the project --- docs/how-to/custom-app.rst | 12 ++--- docs/reference/stack.rst | 9 ++-- docs/reference/units/exporter.rst | 6 +-- docs/reference/units/job.rst | 46 ++++++++++---------- docs/reference/units/packaging-meta-data.rst | 4 +- docs/reference/units/resource.rst | 16 +++---- docs/reference/units/rfc822.rst | 4 +- docs/reference/units/test-plan.rst | 31 +++++++------ 8 files changed, 63 insertions(+), 65 deletions(-) diff --git a/docs/how-to/custom-app.rst b/docs/how-to/custom-app.rst index 7d0e20836b..5fdfd4812c 100644 --- a/docs/how-to/custom-app.rst +++ b/docs/how-to/custom-app.rst @@ -28,7 +28,7 @@ Let's create a Checkbox Snap for project called "myproject". .. code-block:: bash - $ ./configure --with-provider-included project=myproject base=18 && ./cleanup.sh + $ ./configure --with-provider-included project=myproject base=18 This creates all the files necessary to use Snapcraft to build the new snap. @@ -48,7 +48,7 @@ provider. .. code-block:: bash - $ cd checkbox-provider-myproject + $ cd checkbox-myproject/checkbox-provider-myproject Let's add a job from :ref:`tutorials` @@ -74,9 +74,9 @@ in another provider it is best to reference that provider in the snap, and include the test, or whole test plans from that provider in your new testing project. -Let's reuse disk tests from the "plainbox-provider-snappy" provider that we -can use from the checkbox generic snap. All we need to do is add chosen tests -to the ``include`` field of the test plan. +Let's reuse disk tests from the "base" provider that we can use from the +"checkbox" generic snap. All we need to do is add chosen tests to the +``include`` field of the test plan. .. code-block:: none :caption: units/test-plan.pxu @@ -95,7 +95,7 @@ to the ``include`` field of the test plan. (...) You can also include the whole *external* test plan. Let's reuse the CPU -testing suite from plainbox-provider-snappy. +testing suite from the base provider. .. code-block:: none :caption: unit/test-plan.pxu diff --git a/docs/reference/stack.rst b/docs/reference/stack.rst index 17c1f9c5cc..8a03a0a116 100644 --- a/docs/reference/stack.rst +++ b/docs/reference/stack.rst @@ -43,10 +43,11 @@ Component Descriptions | Checkbox Support | - Support code for various providers | Library | | | - Parsers for many text formats | | +------------------------+---------------------------------------+-------------+ -| Plainbox | - Almost all core logic | Library | -| (part of Checkbox) | | and | -| | - RFC822 (job definition) parser | Development | -| | - Configuration handling | Toolkit | +| Plainbox | - An obsolete term referring to the | Library | +| (part of Checkbox) | core of Checkbox | and | +| | | Development | +| | - RFC822 (job definition) parser | Toolkit | +| | - Configuration handling | | | | - Testing session (suspend/resume) | | | | - Job runner | | | | - Trusted launcher | | diff --git a/docs/reference/units/exporter.rst b/docs/reference/units/exporter.rst index 8d91e5edbc..e886927f2b 100644 --- a/docs/reference/units/exporter.rst +++ b/docs/reference/units/exporter.rst @@ -3,7 +3,7 @@ Exporter Unit ============= The purpose of exporter units is to provide an easy way to customize the -plainbox reports by delegating the customization bits to providers. +Checkbox reports by delegating the customization bits to providers. Each exporter unit expresses a binding between code (the entry point) and data. Data can be new options, different Jinja2 templates and/or new paths to load @@ -12,8 +12,8 @@ them. File format and location ------------------------ -Exporter entry units are regular plainbox units and are contained and shipped -with plainbox providers. In other words, they are just the same as job and test +Exporter entry units are regular Checkbox units and are contained and shipped +with Checkbox providers. In other words, they are just the same as job and test plan units, for example. Fields diff --git a/docs/reference/units/job.rst b/docs/reference/units/job.rst index ba12e4a3a5..2215abb705 100644 --- a/docs/reference/units/job.rst +++ b/docs/reference/units/job.rst @@ -131,8 +131,6 @@ Following fields may be used by the job unit: run (regardless of the outcome). Multiple job names, separated by spaces, can be specified. - This feature is available since plainbox 0.24. - .. _Job salvages field: ``salvages``: @@ -217,16 +215,16 @@ Following fields may be used by the job unit: expected to run for, as a positive float value indicating the estimated job duration in seconds. - Since plainbox version 0.24 this field can be expressed in two formats. The - old format, a floating point number of seconds is somewhat difficult to - read for larger values. To avoid mistakes test designers can use the second - format with separate sections for number of hours, minutes and seconds. The - format, as regular expression, is ``(\d+h)?[: ]*(\d+m?)[: ]*(\d+s)?``. The - regular expression expresses an optional number of hours, followed by the - ``h`` character, followed by any number of spaces or ``:`` characters, - followed by an optional number of minutes, followed by the ``m`` character, - again followed by any number of spaces or ``:`` characters, followed by the - number of seconds, ultimately followed by the ``s`` character. + This field can be expressed in two formats. The old format, a floating + point number of seconds is somewhat difficult to read for larger values. To + avoid mistakes test designers can use the new format with separate + sections for number of hours, minutes and seconds. The format, as regular + expression, is ``(\d+h)?[: ]*(\d+m?)[: ]*(\d+s)?``. The regular expression + expresses an optional number of hours, followed by the ``h`` character, + followed by any number of spaces or ``:`` characters, followed by an + optional number of minutes, followed by the ``m`` character, again followed + by any number of spaces or ``:`` characters, followed by the number of + seconds, ultimately followed by the ``s`` character. The values can no longer be fractional (you cannot say ``2.5m`` you need to say ``2m 30s``). We feel that sub-second granularity does is too @@ -236,8 +234,8 @@ Following fields may be used by the job unit: ``flags``: (optional) This fields contains list of flags separated by spaces or - commas that might induce plainbox to run the job in particular way. - Currently, following flags are inspected by plainbox: + commas that might induce Checkbox to run the job in particular way. + Currently, following flags are inspected by Checkbox: .. _reset-locale flag: @@ -247,17 +245,17 @@ Following fields may be used by the job unit: .. _win32 flag: ``win32``: - This flag makes plainbox run jobs' commands in windows-specific manner. + This flag makes Checkbox run jobs' commands in windows-specific manner. Attach this flag to jobs that are run on Windows OS. .. _noreturn flag: ``noreturn``: - This flag makes plainbox suspend execution after job's command is run. - This prevents scenario where plainbox continued to operate (writing + This flag makes Checkbox suspend execution after job's command is run. + This prevents scenario where Checkbox continued to operate (writing session data to disk and so on), while other process kills it (leaving - plainbox session in unwanted/undefined state). - Attach this flag to jobs that cause killing of plainbox process during + Checkbox session in unwanted/undefined state). + Attach this flag to jobs that cause killing of Checkbox process during their operation. E.g. run shutdown, reboot, etc. This flag also makes Checkbox to leave a ``__checkbox_respawn`` file in the ``$PLAINBOX_SESSION_SHARE`` directory which can be used by the @@ -272,16 +270,16 @@ Following fields may be used by the job unit: .. _has-leftovers flag: ``has-leftovers``: - This flag makes plainbox silently ignore (and not log) any files left + This flag makes Checkbox silently ignore (and not log) any files left over by the execution of the command associated with a job. This flag is useful for jobs that don't bother with maintenance of temporary directories and just want to rely on the one already created by - plainbox. + Checkbox. .. _simple flag: ``simple``: - This flag makes plainbox disable certain validation advice and have + This flag makes Checkbox disable certain validation advice and have some sensible defaults for automated test cases. This simplification is meant to cut the boiler plate on jobs that are closer to unit tests than elaborate manual interactions. @@ -302,7 +300,7 @@ Following fields may be used by the job unit: .. _preserve-cwd flag: ``preserve-cwd``: - This flag makes plainbox run the job command in the current working + This flag makes Checkbox run the job command in the current working directory without creating a temp folder (and running the command from this temp folder). Sometimes needed on snappy (See http://pad.lv/1618197) @@ -310,7 +308,7 @@ Following fields may be used by the job unit: .. _fail-on-resource flag: ``fail-on-resource``: - This flag makes plainbox fail the job if one of the resource + This flag makes Checkbox fail the job if one of the resource requirements evaluates to False. .. _also-after-suspend flag: diff --git a/docs/reference/units/packaging-meta-data.rst b/docs/reference/units/packaging-meta-data.rst index db2034de34..daf9559e8b 100644 --- a/docs/reference/units/packaging-meta-data.rst +++ b/docs/reference/units/packaging-meta-data.rst @@ -13,8 +13,8 @@ provider and makes package management largely automatic. File format and location ------------------------ -Packaging meta-data units are regular plainbox units and are contained and -shipped with plainbox providers. In other words, they are just the same as job +Packaging meta-data units are regular Checkbox units and are contained and +shipped with Checkbox providers. In other words, they are just the same as job and test plan units, for example. Fields diff --git a/docs/reference/units/resource.rst b/docs/reference/units/resource.rst index a82a7f88b4..ee26776441 100644 --- a/docs/reference/units/resource.rst +++ b/docs/reference/units/resource.rst @@ -86,8 +86,8 @@ be compatible with the identifier syntax. It can also be used to refer to resources from another namespace. In the examples elsewhere in this page the ``package`` resources are generated -by the ``package`` job. Plainbox uses this to know which resources to try but -also to implicitly to express dependencies so that the ``package`` job does not +by the ``package`` job. Checkbox uses this to know which resources to try but +also to implicitly express dependencies so that the ``package`` job does not have to be explicitly selected and marked for execution prior to the job that in fact depends on it. This is all done automatically. @@ -135,7 +135,7 @@ Now the power-management/rtc job will only be run on systems where Evaluation ---------- -1. First Plainbox looks at the resource program and splits it into lines. Each +1. First Checkbox looks at the resource program and splits it into lines. Each non-empty line is parsed and converted to a resource expression. 2. **unexpected** Each resource expression is repeatedly evaluated, once for @@ -159,11 +159,11 @@ in practice. Joins are not optimized ^^^^^^^^^^^^^^^^^^^^^^^ -Starting with plainbox 0.24, a resource expression can use more than one -resource object (resource job) at the same time. This allows the use of joins -as the whole expression is evaluated over the Cartesian product of all the -resource records. This operation is not optimized, you can think of it as a -JOIN that is performed on a database without any indices. +A resource expression can use more than one resource object (resource job) at +the same time. This allows the use of joins as the whole expression is +evaluated over the Cartesian product of all the resource records. This +operation is not optimized, you can think of it as a JOIN that is performed on +a database without any indices. Let's look at a practical example:: diff --git a/docs/reference/units/rfc822.rst b/docs/reference/units/rfc822.rst index 01fd84925a..4a4ea91d89 100644 --- a/docs/reference/units/rfc822.rst +++ b/docs/reference/units/rfc822.rst @@ -1,11 +1,11 @@ .. _rfc822: ============================= -Plainbox RFC822 Specification +Checkbox RFC822 Specification ============================= The syntax is only loosely inspired by the actual :RFC:`822` syntax. Since -Plainbox is not processing email, the original specification is used only as an +Checkbox is not processing email, the original specification is used only as an inspiration. One of the most important aspect of the syntax we're using is relative familiarity for other users of the system and ease-of-use when using general, off-the-shelf text editors. diff --git a/docs/reference/units/test-plan.rst b/docs/reference/units/test-plan.rst index d3b008f52c..63a03e955c 100644 --- a/docs/reference/units/test-plan.rst +++ b/docs/reference/units/test-plan.rst @@ -175,8 +175,7 @@ copy such constructs when working on a new test plan from scratch that should be excluded from execution. This optional field can be used to prevent some jobs from being selected - for execution. It follows the similarly named ``-x`` command line option - to the ``plainbox run`` command. + for execution. This field may be used when a general (broad) selection is somehow made by the ``include`` field and it must be trimmed down (for example, to @@ -191,10 +190,10 @@ copy such constructs when working on a new test plan from scratch A multi-line list of category override statements. This optional field can be used to alter the natural job definition - category association. Currently Plainbox allows each job definition to - associate itself with at most one category (see plainbox-category-units(7) - and plainbox-job-units(7) for details). This is sub-optimal as some tests - can be easily assigned equally well to two categories at the same time. + category association. Currently Checkbox allows each job definition to + associate itself with at most one category (see :doc:`category` and + :doc:`job` for details). This is sub-optimal as some tests can be easily + assigned equally well to two categories at the same time. For that reason, it may be necessary, in a particular test plan, to override the natural category association with one that more correctly @@ -242,16 +241,16 @@ copy such constructs when working on a new test plan from scratch ``estimated_duration``: An approximate time to execute this test plan, in seconds. - Since plainbox version 0.24 this field can be expressed in two formats. The - old format, a floating point number of seconds is somewhat difficult to - read for larger values. To avoid mistakes test designers can use the second - format with separate sections for number of hours, minutes and seconds. The - format, as regular expression, is ``(\d+h)?[: ]*(\d+m?)[: ]*(\d+s)?``. The - regular expression expresses an optional number of hours, followed by the - ``h`` character, followed by any number of spaces or ``:`` characters, - followed by an optional number of minutes, followed by the ``m`` character, - again followed by any number of spaces or ``:`` characters, followed by the - number of seconds, ultimately followed by the ``s`` character. + This field can be expressed in two formats. The old format, a floating + point number of seconds is somewhat difficult to read for larger values. To + avoid mistakes test designers can use the new format with separate sections + for number of hours, minutes and seconds. The format, as regular + expression, is ``(\d+h)?[: ]*(\d+m?)[: ]*(\d+s)?``. The regular expression + expresses an optional number of hours, followed by the ``h`` character, + followed by any number of spaces or ``:`` characters, followed by an + optional number of minutes, followed by the ``m`` character, again followed + by any number of spaces or ``:`` characters, followed by the number of + seconds, ultimately followed by the ``s`` character. The values can no longer be fractional (you cannot say ``2.5m`` you need to say ``2m 30s``). We feel that sub-second granularity does is too