diff --git a/source/clear-linux/guides/maintenance/mixer.rst b/source/clear-linux/guides/maintenance/mixer.rst index 341f65c0..7178d7ba 100644 --- a/source/clear-linux/guides/maintenance/mixer.rst +++ b/source/clear-linux/guides/maintenance/mixer.rst @@ -3,18 +3,18 @@ Use mixer tool ############## -*Mixing* refers to composing an operating system for specific use cases. While -the default |CLOSIA| provides options to install bundles for various server -capabilities, some developers may wish to either augment the operating system -itself with functionality from their own packages or modify the structure of -current bundles to cater to their particular needs. +*Mixing* refers to composing an operating system for specific use cases. +While the default |CLOSIA| provides options to install bundles for various +server capabilities, some developers may wish to either augment the +operating system itself with functionality from their own packages or modify +the structure of current bundles to cater to their particular needs. Prerequisites ************* To start working with the mixer tools, you need a recent image of |CL| with -the `mixer` bundle installed. If the bundle is not yet installed, you can add it -with the :command:`swupd bundle-add` command as follows: +the `mixer` bundle installed. If the bundle is not yet installed, you can +add it with the :command:`swupd bundle-add` command as follows: .. code-block:: bash @@ -56,8 +56,8 @@ these workflows. Create a workspace ****************** -Create an empty directory in your |CL| image to use as a **workspace** for -mixing with the following command: +Use the following command to create an empty directory in your |CL| image to +use as a **workspace** for mixing: .. code-block:: bash @@ -74,14 +74,15 @@ In your workspace, initialize mixer with the following command: sudo mixer init -This command initializes your workspace for you to make a mix at version 10 +This command initializes your workspace so you can make a mix at version 10 based on the latest released upstream |CL| version. If a :file:`builder.conf` -file is not already present in your workspace, mixer creates a default configuration -file along with several version and tracking files and two bundle directories: -:file:`local-bundles` and :file:`upstream-bundles`. +file is not already present in your workspace, mixer creates a default +configuration file, several version and tracking files, and two bundle +directories: :file:`local-bundles` and :file:`upstream-bundles`. If you wish to start with a different version of upstream |CL| or a -different initial mix version, these options can be specified as flags, for example: +different initial mix version, you can specify these options as flags. +For example: .. code-block:: bash @@ -89,29 +90,29 @@ different initial mix version, these options can be specified as flags, for exam Additionally, to build a mix with your own custom RPMs, use the optional - :option:`--local-rpms` flag, for example: + :option:`--local-rpms` flag. For example: .. code-block:: bash sudo mixer init --local-rpms -This command creates the :file:`local-yum` and :file:`local-rpms` directories in your -mix workspace and adds their paths to the generated :file:`builder.conf`. For more -information on using these directories or setting them up manually, see -`Create or locate RPMs for the mix`_. +This command creates the :file:`local-yum` and :file:`local-rpms` +directories in your mix workspace and adds their paths to the generated +:file:`builder.conf`. For more information on using these directories or +setting them up manually, see `Create or locate RPMs for the mix`_. If all upstream |CL| bundles are part of the mix, you can easily add them all -during initialization with the optional :option:`--all-upstream` flag, for +during initialization with the optional :option:`--all-upstream` flag. For example: .. code-block:: bash sudo mixer init --all-upstream -Finally, you may want to track the contents of your mixer workspace with a Git -repository. This is a great way to track changes to your mix's content or to -revert to earlier versions if something goes wrong. Mixer can set this up -automatically with the optional :option:`--git` flag, for example: +Finally, you may want to track the contents of your mixer workspace with a +git repository. This is a great way to track changes to your mix's content +or to revert to earlier versions if something goes wrong. Mixer can set this +up automatically with the optional :option:`--git` flag. For example: .. code-block:: bash @@ -127,13 +128,13 @@ automatically with the optional :option:`--git` flag, for example: Edit builder.conf ***************** -To configure the mixer tool, you must edit the :file:`builder.conf` as needed. +To configure the mixer tool, edit the :file:`builder.conf` as needed. -The file :file:`builder.conf` is read automatically from the current workspace -directory. Use the :option:`--config` flag during initialization to specify a -alternate path to the file as needed. +The file :file:`builder.conf` is read automatically from the current +workspace directory. Use the :option:`--config` flag during initialization +to specify an alternate path to the file as needed. -The :file:`builder.conf` file has different sections, for example: +The :file:`builder.conf` file has different sections. For example: * The `[Builder]` section provides the mixer tools with the required configuration options. This section defines the path where the generated @@ -179,17 +180,19 @@ The following variables require further explanation: * The `LOCAL_BUNDLE_DIR` variable sets the path where mixer stores the local bundle definition files. These bundle definition files include any new, - original bundles you create and edited versions of upstream |CL| bundles. + original bundles you create, along with any edited versions of upstream + |CL| bundles. * The `SERVER_STATE_DIR` variable sets the path for the output of the mix - content. Mixer automatically creates the path for you but the path can be + content. Mixer automatically creates the path for you, but the path can be set to any location. In this example, we use the workspace directory. -* The `BUNDLE_DIR` sets the path where mixer temporarily stores the bundle - definition files while building chroots. Only the legacy chroot-builder uses - this path. By default, mixer does not generate this directory until needed. - In our example, the path is set to :file:`/home/clr/mix/mix-bundles`. The - new chroot-builder does not generate the folder at all. +* The `BUNDLE_DIR` variable sets the path where mixer temporarily stores the + bundle definition files while building chroots. Only the legacy + chroot-builder uses this path. By default, mixer does not generate this + directory until the directory is needed. In our example, the path is set to + :file:`/home/clr/mix/mix-bundles`. The new chroot-builder does not generate + the folder at all. * The `YUM_CONF` variable sets path where mixer automatically generates the :file:`.yum-mix.conf` yum configuration file. The yum configuration file @@ -200,33 +203,32 @@ The following variables require further explanation: certificate file to sign the root :file:`Manifest.MoM` file to provide security for content verification. The value of the `CERT` variable can point to a different certificate. The chroot-builder inserts the - certificate specified here in the + certificate specified in this value into the :file:`/os-core-update/usr/share/clear/update-ca/` path. The software - update client uses this certificate to - verify the :file:`Manifest.MoM` file's signature. For now, we **strongly** - recommend not to modify this line as the certificate `swupd` expects needs - a very specific configuration to sign and verify properly. Mixer - automatically generates the certificate and signs the - :file:`Manifest.MoM` file providing security for your created update - content. + update client uses this certificate to verify the :file:`Manifest.MoM` + file's signature. For now, we **strongly** recommend that you do not + modify this line, as the certificate that `swupd` expects needs to have a + very specific configuration to sign and verify properly. Mixer + automatically generates the certificate and signs the :file:`Manifest.MoM` + file to provide security for the updated content you create. * The `CONTENTURL` and `VERSIONURL` variables set the domain or IP address where mixer serves your updated content and the corresponding version. You - can set the `CONTENTURL` and `VERSIONURL` URL variables to the domain or IP- + can set the `CONTENTURL` and `VERSIONURL` URL variables to the domain or IP address of the update server. The `SERVER_STATE_DIR` directory is hosted here: :file:`/home/clr/mix/update/www`. Creating a symlink to the directory in your server webdir is an easy way to host the content. These URLs are embedded in images created for your mix. The `swupd-client` looks at these - URLs to figure out if there is a new version available and the location from - which to download the updated content. Think of these links as the + URLs to determine both if there is a new version available and the location + from which to download the updated content. Think of these links as the equivalent to the |CL| `update page`_ but for your mix. * The `FORMAT` variable relates to the format bump. To learn more about the - `FORMAT` option, see :ref:`mixer-format` and the `format bumps wiki`_. For - now, leave the `FORMAT` value unchanged. + `FORMAT` option, refer to :ref:`mixer-format` and the `format bumps wiki`_. + For now, leave the `FORMAT` value unchanged. -* The `VERSIONS_PATH` variable set the path for the mix version and upstream - |CL| version two state files: :file:`mixversion` and +* The `VERSIONS_PATH` variable sets the path for the mix version and upstream + |CL| version's two state files: :file:`mixversion` and :file:`upstreamversion`. Mixer creates both files for you when you set up the workspace. @@ -237,18 +239,18 @@ Create or locate RPMs for the mix ********************************* If you create RPMs from scratch, you can use `autospec`, `mock`, `rpmbuild`, -or similar tools to build them. If the RPMs are not built on |CL|, ensure your -configuration and tool-chain builds them correctly for Clear or there is no -guarantee they will be compatible. For more information on building the RPMs -properly visit our `build RPMs instructions`_. +or similar tools to build them. If the RPMs are not built on |CL|, ensure +your configuration and toolchain builds them correctly for |CL|, or else +there is no guarantee they will be compatible. For more information on +building the RPMs properly, refer to our `build RPMs instructions`_. Import RPMs into workspace ************************** -#. Create a :file:`local-rpms` directory in your workspace, for example +#. Create a :file:`local-rpms` directory in your workspace. For example, :file:`/home/clr/mix/local-rpms`. -#. Copy the RPMs into the created directory. +#. Copy the RPMs into the directory you created. #. Add the following line to your :file:`builder.conf` file: @@ -269,25 +271,27 @@ Create a local RPM repo LOCAL_REPO_DIR=/home/clr/mix/local-yum -#. With these values configured, generate the yum repo with the following command: +#. With these values configured, generate the yum repo with the following + command: .. code-block:: bash sudo mixer add-rpms -After the tool exits, you should see the RPMs and a repository data directory in -:file:`/home/clr/mix/local-yum`. If the RPMs are not all in this -:file:`local-yum` directory, check to ensure they are valid RPM files and not -corrupt. +After the tool exits, you should see the RPMs and a repository data +directory in :file:`/home/clr/mix/local-yum`. If the RPMs are not all in this +:file:`local-yum` directory, check to ensure that the RPM files are valid +and not corrupt. List, edit, create, add, remove, or validate bundles **************************************************** The bundles in the mix are specified in the mix bundle list. Mixer stores -this list as a flat file called :file:`mixbundles` in the path set in the -`VERSIONS_PATH` variable of the :file:`builder.conf` file. Mixer generates -the mix bundle list file automatically during initialization. Mixer reads -and writes the bundle list file when you change the bundles of the mix. +this list as a flat file called :file:`mixbundles` in the path set by the +`VERSIONS_PATH` variable of the :file:`builder.conf` file. Mixer +automatically generates the :file:`mixbundles` list file during +initialization. Mixer reads and writes the bundle list file when you change +the bundles of the mix. List the bundles in the mix =========================== @@ -298,54 +302,56 @@ To view the bundles already in the mix, enter the following command: sudo mixer bundle list -The command shows a list of every bundle in the mix. Bundles can include other -bundles and those bundles can themselves include other bundles. When listing -the bundles with this command, mixer automatically recurses through the -includes to show every single bundle in the mix. +This command shows a list of every bundle in the mix. Bundles can include +other bundles, and those nested bundles can themselves include other +bundles. When listing bundles with this command, mixer automatically +recurses through the includes to show every single bundle in the mix. -If you see an unexpected bundle in the list, the bundle probably is included -in another bundle. Use the :option:`--tree` flag to get a better view of how a -bundle ended up in the mix, for example: +If you see an unexpected bundle in the list, that bundle is probably included +in another bundle. Use the :option:`--tree` flag to get a better view of how +a bundle ended up in the mix. For example: .. code-block:: bash sudo mixer bundle list --tree -This command prints a tree view of the mix bundle list explicitly showing each -included bundle. +This command prints a tree view of the mix bundle list that explicitly shows +each included bundle. Bundles fall into two categories: **upstream** and **local**. Upstream bundles are those provided by |CL|. -Mixer automatically downloads and caches upstream bundle definition files. The -definition files are stored in the :file:`upstream-bundles` directory in the -workspace. Do **not** modify the files in this directory. The directory is -simply a mirror for mixer to use. +Mixer automatically downloads and caches upstream bundle definition files. +These definition files are stored in the :file:`upstream-bundles` directory +in the workspace. Do **not** modify the files in this directory. This +directory is simply a mirror for mixer to use. -The mixer tool automatically caches the bundles for the |CL| version configured in the -:file:`upstreamversion` file. Mixer also cleans up old versions once they are no -longer needed. See the available upstream bundles with the following command: +The mixer tool automatically caches the bundles for the |CL| version +configured in the :file:`upstreamversion` file. Mixer also cleans up old +versions once they are no longer needed. You can see the available upstream +bundles with the following command: .. code-block:: bash sudo mixer bundle list upstream -Local bundles are bundles you create or edited versions of upstream bundles. +Local bundles are bundles that you create, or are edited versions of upstream +bundles. Local bundle definition files live in the :file:`local-bundles` directory. The `LOCAL_BUNDLE_DIR` variable sets the path of this directory in your :file:`builder.conf` configuration file. For this example, the path is -:file:`/home/clr/mix/local-bundles`. See the available local bundles with the -following command: +:file:`/home/clr/mix/local-bundles`. You can see the available local bundles +with the following command: .. code-block:: bash sudo mixer bundle list local -Both the local or upstream :command:`bundle list` commands accept the -:option:`--tree` flag to print a tree view explicitly showing each included -bundle. +Both the local and upstream :command:`bundle list` commands accept the +:option:`--tree` flag to print a tree view that explicitly shows each +included bundle. Edit the bundles in the mix =========================== @@ -353,9 +359,9 @@ Edit the bundles in the mix **Mixer always checks local bundles first and the upstream bundles second.** Therefore, bundles in the :file:`local-bundles` directory always take -precedence over the upstream bundles of the same name. +precedence over any upstream bundles that have the same name. -This precedence enables the editing of upstream bundles. The local, edited +This precedence enables you to edit upstream bundles. The local, edited version of the bundle overrides the bundle version found upstream. For example, to edit the `bundle1` definition file, we use the following @@ -365,9 +371,10 @@ command: sudo mixer bundle edit bundle1 -If `bundle1` is found in your local bundles, mixer edits the bundle definition -file. If instead `bundle1` is only found upstream, mixer copies the bundle -definition file from upstream into your :file:`local-bundles` directory first. +If `bundle1` is found in your local bundles, mixer edits the bundle +definition file. If instead `bundle1` is only found upstream, mixer copies +the bundle definition file from upstream into your :file:`local-bundles` +directory first. In both cases, mixer launches your default editor to edit the file. When the editor closes, mixer automatically validates the edited bundle file and @@ -386,7 +393,7 @@ Create bundles for the mix ========================== To create a totally **new bundle**, the bundle name you specify cannot exist -upstream. If that is the case, create a `new-bundle` with the following +upstream. If that is the case, create a :file:`new-bundle` with the following command: .. code-block:: bash @@ -394,14 +401,15 @@ command: sudo mixer bundle edit new-bundle This command generates a blank template in :file:`local-bundles` with the -:file:`new-bundle` filename. Mixer launches the editor for you to fill out the -bundle and performs validation on exiting. Add your package or packages in the -bundle definition file to define the packages to install as part of the bundle. +:file:`new-bundle` filename. Mixer launches the editor for you to fill out +the bundle and performs validation when you exit the editor. Add your package +or packages to the bundle definition file to define the packages to install +as part of the bundle. .. note:: The :command:`mixer bundle edit` accepts multiple bundles at once. Thus, - you can create multiple new bundles in a single command, for example: + you can create multiple new bundles in a single command. For example: .. code-block:: bash @@ -410,19 +418,19 @@ bundle definition file to define the packages to install as part of the bundle. Add bundles to the mix ====================== -Add `bundle1` to your mix easily with the following command: +You can add `bundle1` to your mix with the following command: .. code-block:: bash sudo mixer bundle add bundle1 -This command adds the bundles you specify to your mix bundles list stored in -the :file:`mixbundles` file. For each bundle you add, mixer checks your local -and upstream bundles to ensure the added bundle actually exists. If mixer -cannot find the bundle, it reports back an error. Additionally, when mixer -adds a bundle, it tells you whether the bundle is local or upstream. +This command adds the specified bundles to the mix bundles list stored in +your :file:`mixbundles` file. For each bundle you add, mixer checks your +local and upstream bundles to ensure the added bundles actually exist. If +mixer cannot find the bundle, it reports back an error. Additionally, when +mixer adds a bundle, it tells you whether the bundle is local or upstream. Alternatively, you can learn this information with the -:command:`mixer bundle list` command, see `List the bundles in the mix`_. +:command:`mixer bundle list` command. Refer to `List the bundles in the mix`_. To add multiple bundles at once, use the following command: @@ -439,31 +447,31 @@ Remove `bundle1` from your mix with the following command: sudo mixer bundle remove bundle1 -This command remove the `bundle1` from the mix bundle list stored in the -:file:`mixbundles` file. By default, the command does not remove the bundle +This command removes `bundle1` from the mix bundle list stored in your +:file:`mixbundles` file. By default, this command does not remove the bundle definition file from your local bundles. To completely remove a bundle, -including its local bundle definition file, use the following command with the -:option:`--local` flag: +including its local bundle definition file, use the following command with +the :option:`--local` flag: .. code-block:: bash sudo mixer bundle remove --local bundle1 By default, removing a local bundle file with this command removes the bundle -from the mix as well. To only remove the local bundle definition file, use the -following command with the :option:`--mix=false` flag: +from the mix as well. To only remove the local bundle definition file, use +the following command with the :option:`--mix=false` flag: .. code-block:: bash sudo mixer bundle remove --local --mix=false bundle1 -If you remove a local edited version of an upstream bundle and keep the bundle -in the mix, the mix then references the original upstream version of the -bundle. +If you remove a local, edited version of an upstream bundle and keep the +bundle in the mix, the mix then references the original upstream version of +the bundle. -On the other hand, if you remove a bundle only found locally but keep the -bundle in the mix bundles list, mixer will no longer find a valid bundle -definition file and will produce an error. +On the other hand, if you remove a bundle that is only found locally but +keep the bundle in the mix bundles list, mixer will not find a valid +bundle definition file and will produce an error. Validate the bundles in the mix =============================== @@ -472,17 +480,18 @@ Mixer performs basic **validation** on all bundles when used throughout the system. Mixer checks the validity of the bundle's syntax and name. Mixer also ensures -the bundle can be parsed. Run this validation manually on bundle1 with the +the bundle can be parsed. Run this validation manually on `bundle1` with the following command: .. code-block:: bash sudo mixer bundle validate bundle1 -With the optional :option:`--strict` flag, the command additionally -checks if the rest of the bundle header fields can be parsed, if they are -non-empty, and if the bundle header ``Title`` field and the bundle filename -match. Perform a strict validation of `bundle1` with the following command: +If you use the optional :option:`--strict` flag, the command additionally +checks if the rest of the bundle header fields can be parsed, if the bundle +header fields are non-empty, and if the bundle header ``Title`` field and +the bundle filename match. Perform a strict validation of `bundle1` with the +following command: .. code-block:: bash @@ -497,13 +506,14 @@ Validate multiple bundles with the following command: Managing bundles with Git ========================= -If you initialized your workspace to be tracked as a Git repository -with the :command:`mixer init --git` command, it might be useful to apply a git -commit after modifying the mix bundle list or editing a bundle definition file. +If you initialized your workspace to be tracked as a git repository +with the :command:`mixer init --git` command, it might be useful to apply a +git commit after you modify the mix bundle list or edit a bundle definition +file. -All the :command:`mixer bundle` commands on the previous sections support an -optional :option:`--git` flag. The flag automatically applies a git commit -when the command completes, for example: +All the :command:`mixer bundle` commands in the previous sections support an +optional :option:`--git` flag. This flag automatically applies a git commit +when the command completes. For example: .. code-block:: bash @@ -525,20 +535,21 @@ By default, mixer uses the legacy chroot-builder. In this mode, mixer automatically gathers the bundle definition files for the bundles in the mix into a :file:`mix-bundles` directory. The directory's path is set in the `BUNDLE_DIR` variable in the :file:`builder.conf`. **Do not edit these -files.** Mixer automatically clears out any contents in this directory before -populating it on-the-fly as mixer builds the chroots. +files.** Mixer automatically deletes the contents of the :file:`mix-bundles` +directory before repopulating the directory on-the-fly as mixer builds the +chroots. -We have build a new chroot-builder into the mixer tool itself. While this is -currently an experimental feature, you should use the new chroot-builder. To use -the new chroot-builder, use the following command with the +We have built a new chroot-builder into the mixer tool itself. While this is +currently an experimental feature, you should use the new chroot-builder. To +use the new chroot-builder, use the following command with the :option:`--new-chroots` flag: .. code-block:: bash sudo mixer build chroots --new-chroots -We will soon deprecate the legacy chroot-builder and mixer will use the new version -automatically. +We will soon deprecate the legacy chroot-builder. When we do, mixer will use +the new version automatically. Create an update **************** @@ -552,28 +563,28 @@ Create an update with the following command: When the build completes, you can find the mix update content under :file:`/home/clr/mix/update/www/VER`. In our example, the update content is found in :file:`/home/clr/mix/update/www/{}`. `` -is the mix version defined, 10 by default. +is the defined mix version, which is 10 by default. By default, mixer uses the legacy `swupd-server` to generate the update -content. We have built a new implementation into the mixer tool itself. While -this is currently an experimental feature, you should use the new swupd- -server. To use the the new swupd-server, use the following command with the -:option:`--new-swupd` flag: +content. However, we have built a new implementation into the mixer tool +itself. While this is currently an experimental feature, you should use the +new `swupd-server`. To use the the new `swupd-server`, use the following +command with the :option:`--new-swupd` flag: .. code-block:: bash sudo mixer build update --new-swupd -We will soon deprecate the legacy swupd-server and mixer will use the new version -automatically. +We will soon deprecate the legacy `swupd-server`. When we do, mixer will use +the new version automatically. Mixer creates all the content needed to make a fully usable mix with this step. However, only *zero packs* are automatically generated. Zero packs are the content needed to go from nothing to the mix version for which you just built the content. -Create optional *delta packs*, which allow the transition from one mix version -to another, with the following command: +You can create optional *delta packs*, which allow the transition from one +mix version to another, with the following command: .. code-block:: bash @@ -581,20 +592,20 @@ to another, with the following command: The pack-maker generates all delta packs for the bundles changed from `PAST_VERSION` to `MIX_VERSION`. If your `STATE_DIR` is in a different -location, specify the location with the :option:`-S` flag. Mixer cannot create -delta packs for the first build because the update is from version 0. Version -0 implicitly has no content, thus, mixer can generate no deltas. +location, specify the location with the :option:`-S` flag. Mixer cannot +create delta packs for the first build because the update is from version 0. +Version 0 implicitly has no content. Thus, mixer can generate no deltas. -For subsequent builds, you can run :file:`mixer-pack-maker.sh` to generate -delta content between them, for example: 10 to 20. +For subsequent builds, you can run :file:`mixer-pack-maker.sh` to generate +delta content between them. For example: 10 to 20. Create an image ***************** -Since mixer uses the `ister` tool to create a bootable image from your updated -content, we must first configure the `ister` tool. To configure the image -`ister` creates, we need the `ister` configuration file. Obtain a copy with -the default values from the `ister` package with the following command: +Since mixer uses the `ister` tool to create a bootable image from your +updated content, we must first configure the `ister` tool. To configure the +image `ister` creates, we need the `ister` configuration file. Obtain a copy +with the default values from the `ister` package with the following command: .. code-block:: bash @@ -604,8 +615,8 @@ For reference, you can inspect the `Clear Linux ister configuration file`_ used for releases. Edit the configuration file to include all bundles you want *preinstalled* in -the image. Users can install the bundles in the mix not included in the -configuration file with the following command: +the image. Users can install the bundles in the mix that are not included in +the configuration file with the following command: .. code-block:: bash @@ -618,23 +629,23 @@ smaller image size. For the minimal base image, the list is: "Bundles": ["os-core", "os-core-update", "kernel-native"] -Next, set the `Version` field to the mix version content mixer should use to -build image. `ister` allows you to build an image from any mix version you -have built, not just the current one. In our example so far, `Version` is set -to 10. +Next, set the `Version` field to the mix version that you want the content +mixer to use to build the image. `ister` allows you to build an image from +any mix version that you have built, not just from the current version. In +our example so far, `Version` is set to 10. -With the `ister` tool configured, build the image with with the following command: +With the `ister` tool configured, build the image with the following command: .. code-block:: bash sudo mixer build image --format 1 -This command outputs an image bootable as a virtual machine and which can be -installed on bare metal. +This command outputs an image that is bootable as a virtual machine and +that can be installed on bare metal. -Mixer automatically looks for the :file:`release-image-config.json` file but +Mixer automatically looks for the :file:`release-image-config.json` file, but you can freely choose the filename. To use a different name, simply pass the -:option:`--template` flag when creating your image, for example: +:option:`--template` flag when creating your image. For example: .. code-block:: bash @@ -659,30 +670,31 @@ Increment the mix version number for the next mix with the following command: sudo mixer versions update This command automatically updates the mix version stored in the -:file:`mixversion` file incrementing it by 10. To increment by a different -amount, use the :option:`--increment` flag, for example: +:file:`mixversion` file, incrementing it by 10. To increment by a different +amount, use the :option:`--increment` flag. For example: .. code-block:: bash sudo mixer versions update --increment 100 Alternatively, to set the mix version to a specific value, use the -:option:`--mix-version` flag, for example: +:option:`--mix-version` flag. For example: .. code-block:: bash sudo mixer versions update --mix-version 200 -The :command:`mixer versions update` command does not allow you to set the mix -version to a value lower than its current value. The mix version is expected -to always increase, even if the new mix is undoing an earlier change. +The :command:`mixer versions update` command does not allow you to set the +mix version to a value less than its current value. The mix version is +expected to always increase, even if the new mix is undoing an earlier +change. -If you have been tracking your workspace with Git, you can restore the mix to -an earlier state but be careful of "rewriting history" if you are publishing -the mix content to users already. +If you have been tracking your workspace with git, you can restore the mix to +an earlier state. However, be careful when "rewriting history" if you have +published the mix content to users already. -Update the upstream version of |CL| used as a base for the mix, with the -following command using the :option:`--upstream-version` flag: +Use the following command with the the :option:`--upstream-version` flag to +update the upstream version of |CL| used as a base for the mix: .. code-block:: bash @@ -696,12 +708,12 @@ This command also accepts the keyword "latest": This command sets the upstream version to the latest released version of upstream |CL| within the same format version. The :command:`mixer -versions update` command does not allow to set an upstream version to a -value crossing an upstream format boundary. Such values require a -"format bump" build, which is currently a manual process. See :ref:`mixer-format` -for more information. +versions update` command does not allow you to set an upstream version to a +value that crosses an upstream format boundary. Such values require a +"format bump" build, which is currently a manual process. Refer to +:ref:`mixer-format` for more information. -Learn which mix version or upstream version you currently are on with the +Learn which mix version or upstream version you are currently using with the following command: .. code-block:: bash @@ -724,7 +736,7 @@ modifications as needed. For example: sudo mixer build update -#. Optionally,create delta packs with: +#. Optionally, you can create delta packs with: .. code-block:: bash @@ -735,24 +747,25 @@ modifications as needed. For example: Format version ************** -The `Format` variable set in the :file:`builder.conf` can be more precisely -referred to as an OS *compatibility epoch*. Versions of the OS within a given -epoch are fully compatible and can update to any version in that epoch. Across -the `Format` boundary, the OS has changed in such a way, that updating from -build M in format X, to build N in format Y will not work. Generally, this -scenario occurs when the software updater or manifests change in a way no -longer compatible with the previous update scheme. +The `Format` variable set in the :file:`builder.conf` file can be more +precisely referred to as an OS *compatibility epoch*. Versions of the OS +within a given epoch are fully compatible and can update to any other +version within that epoch. Across the `Format` boundary, the OS has changed +in such a way that updating from build M in format X, to build N in format Y +will not work. Generally, this scenario occurs when the software updater or +software manifests change in a way that they are no longer compatible with +the previous update scheme. Using a format increment, we insure pre- and co-requisite changes flow out with proper ordering. The updated client only ever updates to the latest release in its respective format version, unless overridden by command line -flags. Thus, we can guarantee all clients update to the final version in their -given format. The given format *must* contain all the changes needed to -understand the content built in the subsequent format. Only after reaching the -final release in the old format, can a client continue to update to releases -in the new format. +flags. Thus, we can guarantee that all clients update to the final version +in their given format. The given format *must* contain all the changes +needed to understand the content built in the subsequent format. Only after +reaching the final release in the old format can a client continue to update +to releases in the new format. -When creating a custom mix, the format version should start at '1' or some +When creating a custom mix, the format version should start at `1` or some known number. The format version should increment only when a compatibility breakage is introduced. Normal updates, like updating a software package for example, do not require a format increment.