Merge branch 'main' into ROCKS-902/docs/add-definition-for-overlay-step

docs/.wordlist.txt

@@ -71,8 +71,8 @@ reStructuredText
 rockcraft
 Rockcraft
 Rockcraft's
-ROCK's
-ROCKs
+rock's
+rocks
 runit
 runtime
 Runtime

docs/explanation/chisel.rst

@@ -8,7 +8,7 @@ Debian packages into a filesystem.
 
 Using the analogy of a tool to carve and cut stone, Chisel is used in
 Rockcraft to sculpt minimal collections of files that only include what is
-needed for the ROCK to function properly.
+needed for the rock to function properly.
 
 See :ref:`how_to_use_chisel` for information about using the tool.
 
@@ -42,7 +42,7 @@ With these slice definitions in place, Chisel is able to extract a
 highly-customised and specialised slice of the Ubuntu distribution, which one
 could see as a block of stone from which we can carve and extract only the
 small and relevant parts that we need to run our applications, thus keeping
-ROCKs small and less exposed to vulnerabilities.
+rocks small and less exposed to vulnerabilities.
 
 Defining slices
 ~~~~~~~~~~~~~~~

docs/explanation/overlay-step.rst

@@ -1,10 +1,10 @@
 Overlay step
 ============
 
-The component parts of a ROCK are built in a sequence of
+The component parts of a rock are built in a sequence of
 five separate steps: pull, overlay, build, stage and prime.
 
-The overlay step is specific to ROCKs and is configured with overlay parameters.
+The overlay step is specific to rocks and is configured with overlay parameters.
 To learn more about pull, build, stage and prime see
 :doc:`/reference/part_properties`
 

docs/explanation/pebble.rst

@@ -4,7 +4,7 @@ Pebble
 ======
 
 .. important::
-    **Pebble is the default entrypoint for all ROCKs!**
+    **Pebble is the default entrypoint for all rocks!**
 
 Similar to other well-known process managers such as *supervisord*, *runit*, or
 *s6*, `Pebble`_ is a service manager that enables the seamless orchestration of
@@ -19,7 +19,7 @@ Multiple processes in a container?
 
 Containers' best practices advocate the separation of concerns and the adoption
 of a single service per container. With the introduction of `Pebble`_ as the
-ROCKs' entrypoint, this principle is elevated to new heights:
+rocks' entrypoint, this principle is elevated to new heights:
 
   *if multiple processes rely on shared dependencies and are tightly coupled
   together (i.e. they serve a single purpose and cannot be executed
@@ -40,7 +40,7 @@ Pebble distinguishes itself from other similar tools (like `tini`_ and
 `s6-overlay`_) by offering the following core features:
 
 * **client-server model behind a single binary**: Pebble is injected into
-  ROCKs as a single binary which acts both as a daemon and a client to itself;
+  rocks as a single binary which acts both as a daemon and a client to itself;
 * **declarative service definition**: the Pebble service processes (or simply
   *Pebble services*) are declaratively defined in YAML files called layers.
   Compared to `imperative wrapper scripts (as suggested in the Docker
@@ -53,7 +53,7 @@ Pebble distinguishes itself from other similar tools (like `tini`_ and
 * **layering**: Pebble can stack multiple layers (represented as YAML files)
   into a single Pebble plan where all services are defined. With this layering
   mechanism, existing services can be overridden or re-configured;
-* **container-optimised init process**: as a ROCK's PID 1, Pebble acts as an
+* **container-optimised init process**: as a rock's PID 1, Pebble acts as an
   init process and thus offers:
 
   * support for multiple child processes,
@@ -62,11 +62,11 @@ Pebble distinguishes itself from other similar tools (like `tini`_ and
   * graceful shutdown,
   * log rotation,
   * run the Pebble daemon and client commands in a single operation;
-* **consistent user experience**: since every ROCK has Pebble as its
+* **consistent user experience**: since every rock has Pebble as its
   entrypoint, a predictable and consistent user experience is guaranteed;
-* **embedded utilities**: regardless of the ROCK's contents, Pebble offers a
+* **embedded utilities**: regardless of the rock's contents, Pebble offers a
   comprehensive suite of commands for inspecting and interacting with the
-  container. These commands are especially useful for :ref:`Chiselled ROCKs
+  container. These commands are especially useful for :ref:`Chiselled Rocks
   <chisel_explanation>`, as they encompass functionalities such as listing and
   deleting files, creating directories, and inspecting Pebble services,
   among others.

docs/explanation/rockcraft.rst

@@ -44,7 +44,7 @@ verify that the latter have no high/critical vulnerabilities in them!
   :width: 95%
   :alt: vulnerabilities in Official vs Canonical-maintained OCI images
 
-So this is where the motivation for a new generation of OCI images (aka ROCKs)
+So this is where the motivation for a new generation of OCI images (aka rocks)
 starts - the need for more secure container images! And while this need might
 carry the biggest weight in the container users' demands, other values come into
 play when selecting the best container image, such as:
@@ -56,14 +56,14 @@ play when selecting the best container image, such as:
 
 You can find these values and their relevance in `this report`_.
 
-This brings us to the problem statement behind ROCKs:
+This brings us to the problem statement behind rocks:
 
     *How might we redesign secure container images \
     for Kubernetes developers and application maintainers, \
     considering the Top 10 Docker images \
     are full of vulnerabilities, except Ubuntu?*
 
-A ROCK is:
+A rock is:
 
 * **secure** and **stable**: based on the latest and greatest Ubuntu releases;
 * **OCI-compliant**: compatible with all the popular container management tools
@@ -76,8 +76,8 @@ A ROCK is:
 Do I need to use Rockcraft?
 ---------------------------
 
-If you want to build a proper ROCK, yes, we'd recommend you do. This is not to
-say you wouldn't be able to build ROCK-like container images with your own
+If you want to build a proper rock, yes, we'd recommend you do. This is not to
+say you wouldn't be able to build rock-like container images with your own
 tools, but Rockcraft has been developed precisely to offer an easy way to build
 production-grade container images.
 

docs/explanation/rocks.rst

@@ -1,37 +1,37 @@
 .. _rocks_explanation:
 
-ROCKs
+Rocks
 =====
 
-ROCKs are **Ubuntu LTS-based container images** that are designed to meet
+Rocks are **Ubuntu LTS-based container images** that are designed to meet
 cloud-native software's security, stability, and reliability requirements.
 
-ROCKs comply with the `Open Container Initiative`_'s (OCI) `image format
+Rocks comply with the `Open Container Initiative`_'s (OCI) `image format
 specification <OCI_image_spec_>`_, and can be stored in any OCI-compliant
 container registry (e.g. DockerHub, ECR, ACR,..) and used by any OCI-compliant
 tool (e.g. Docker, Podman, Kubernetes,...).
 
-Interoperability between ROCKs and other containers also extends to how
-container images are built, allowing ROCKs to be used as bases for existing
+Interoperability between rocks and other containers also extends to how
+container images are built, allowing rocks to be used as bases for existing
 build recipes, such as Dockerfiles, for further customisation and development.
 
-What sets ROCKs apart?
+What sets rocks apart?
 ~~~~~~~~~~~~~~~~~~~~~~
 
-* **Opinionated and consistent design**: all ROCKs follow the same design,
+* **Opinionated and consistent design**: all rocks follow the same design,
   aiming to minimise your full-stack disparity and adoption overhead, e.g.
 
   * :ref:`pebble_explanation_page` **is the official entrypoint for all
-    ROCKs**, providing a predictable and powerful abstraction layer
+    rocks**, providing a predictable and powerful abstraction layer
     between the user and the container application;
-  * ROCKs extend the OCI image information by including additional **metadata**
-    inside each ROCK (e.g. at ``/.rock/metadata.yaml``), allowing container
+  * Rocks extend the OCI image information by including additional **metadata**
+    inside each rock (e.g. at ``/.rock/metadata.yaml``), allowing container
     applications to easily inspect the properties of the image they are running
     on, at execution time;
-* **User-centric experience**: ROCKs are described in a :ref:`declarative
+* **User-centric experience**: rocks are described in a :ref:`declarative
   format<rockcraft.yaml_reference>` and **built on top of familiar and reliable
   Ubuntu LTS images**, offering an open and up-to-date user experience;
-* **Seamless chiselling experience**: ROCKs can be effortlessly
+* **Seamless chiselling experience**: rocks can be effortlessly
   :ref:`chiselled<chisel_explanation>` using off-the-shelf primitives,
   harnessing all the advantages of "distroless" to deliver **compact
   and secure Ubuntu-based container images**.
@@ -41,7 +41,7 @@ Design
 ~~~~~~
 
 Given their compliance with the `OCI image specification <OCI_image_spec_>`_,
-all ROCKs are constituted by OCI metadata (like the image's `index`_,
+all rocks are constituted by OCI metadata (like the image's `index`_,
 `manifest`_ and `configuration`_) plus the actual `OCI layers`_ with the
 container filesystem contents.
 
@@ -57,13 +57,13 @@ result from the user's instructions at image build time, and that can be
 accessed by the container application at runtime.
 
 The following diagram depicts the different OCI components in the context of a
-ROCK, highlighting where the aforementioned design features (like the Pebble
+rock, highlighting where the aforementioned design features (like the Pebble
 entrypoint) fit in.
 
 .. figure:: /_static/rock_diagram.png
    :width: 75%
    :align: center
-   :alt: ROCK diagram
+   :alt: Rock diagram
 
 .. _`index`: https://github.com/opencontainers/image-spec/blob/main/image-index.md
 .. _`manifest`: https://github.com/opencontainers/image-spec/blob/main/manifest.md

docs/how-to/code/convert-to-pebble-layer/rockcraft.yaml

@@ -1,9 +1,9 @@
 name: custom-nginx-rock
 base: "[email protected]"
 version: latest
-summary: An NGINX ROCK
+summary: An NGINX rock
 description: |
-    A ROCK equivalent of the official NGINX Docker image from Docker Hub.
+    A rock equivalent of the official NGINX Docker image from Docker Hub.
 license: Apache-2.0
 platforms:
     amd64:

docs/how-to/code/install-slice/rockcraft.yaml

@@ -2,9 +2,9 @@ name: custom-openssl-rock
 base: bare
 build_base: "[email protected]"
 version: '0.0.1'
-summary: A chiselled ROCK with a custom OpenSSL slice
+summary: A chiselled rock with a custom OpenSSL slice
 description: |
-    A ROCK containing only the binaries (and corresponding dependencies) from the OpenSSL package.
+    A rock containing only the binaries (and corresponding dependencies) from the OpenSSL package.
     Built from a custom Chisel release.
 license: GPL-3.0
 platforms:

docs/how-to/convert-to-pebble-layer.rst

@@ -3,7 +3,7 @@ How to convert an entrypoint to a Pebble layer
 
 This guide will show you how to take an existing Docker image entrypoint
 and convert it into a Pebble layer, aka the list of one or more services
-which is defined in ``rockcraft.yaml`` and then taken by the ROCK's
+which is defined in ``rockcraft.yaml`` and then taken by the rock's
 Pebble entrypoint.
 
 
@@ -32,7 +32,7 @@ is composed of metadata, checks and services. The latter is present in
 <https://canonical-rockcraft.readthedocs-hosted.com/en/latest/reference/
 rockcraft.yaml/#format-specification>`_
 and it represents the services which are loaded by the Pebble entrypoint when
-deploying a ROCK.
+deploying a rock.
 
 Given the reference entrypoint, this guide's goal is to create two services:
 one for ``nginx`` and another for ``nginx-debug``. The following ``services``
@@ -46,11 +46,11 @@ This is defining two separate Pebble services which are disabled by default
 at startup, have the same environment variable, but are executed with
 different commands (``nginx`` and ``nginx-debug``).
 
-Build the ROCK
+Build the rock
 --------------
 
 Copy the above snippet and incorporate it into the ``rockcraft.yaml`` file
-which will be used to build your ROCK, as shown below:
+which will be used to build your rock, as shown below:
 
 .. literalinclude:: code/convert-to-pebble-layer/rockcraft.yaml
     :language: yaml
@@ -67,7 +67,7 @@ GPG key ID as the one used in `the Dockerfile
 
 **NOTE**: to add custom configuration files, you can use the ``dump`` plugin.
 
-Now, build the final custom NGINX ROCK with:
+Now, build the final custom NGINX rock with:
 
 .. literalinclude:: code/convert-to-pebble-layer/task.yaml
     :language: bash
@@ -108,7 +108,7 @@ You should see something like this:
     Executed parts lifecycle
     Exported to OCI archive 'custom-nginx-rock_latest_amd64.rock'
 
-Then copy the resulting ROCK (from the OCI archive format) to the Docker daemon
+Then copy the resulting rock (from the OCI archive format) to the Docker daemon
 via:
 
 .. literalinclude:: code/convert-to-pebble-layer/task.yaml

docs/how-to/create-slice.rst

@@ -6,7 +6,7 @@ If your package doesn't yet have the slice definitions you actually need to
 merged upstream for everyone else to use :ref:`publishslice` ).
 
 **Let's assume you are trying to create a slice definition for installing the
-OpenSSL binary into your ROCK!**
+OpenSSL binary into your rock!**
 
 Make sure the slice definition doesn't exist yet
 ------------------------------------------------
@@ -16,7 +16,7 @@ your needs already exists:
 
 #. Look into the upstream `chisel-releases`_ repository
 #. Switch to the branch corresponding to the desired Ubuntu release for your
-   ROCK
+   rock
 #. Search your package name within the list of slice definitions files
 
    * if you find it, open it and try to find a slice name containing the bits
@@ -98,7 +98,7 @@ Create your slice definition
 ----------------------------
 
 You now have everything needed to actually define the OpenSSL slice that will
-install the content you are looking to have in the final ROCK. Since you are
+install the content you are looking to have in the final rock. Since you are
 looking to install just the OpenSSL binaries from the ``openssl`` package, what
 about naming this new slice **bins**? Let's go for it:
 
@@ -139,7 +139,7 @@ definition that only needs the OpenSSL configurations and not the binaries.
 
 And that's it. This is your brand new slice definitions file, which will allow
 Chisel to install **just** the OpenSSL binaries (and their dependencies) into
-your ROCK! To learn about how to actually use this new slice definition file and
+your rock! To learn about how to actually use this new slice definition file and
 publish it upstream for others to use, please check the following guides.
 
 .. _chisel-releases:

docs/how-to/get-started.rst

@@ -7,10 +7,10 @@ Getting started
 ---------------
 
 Rockcraft is **the tool** for building Ubuntu-based and production-grade OCI
-images, aka ROCKs!
+images, aka rocks!
 
-Rockcraft is distributed as a snap. For packing new ROCKs, it makes use of
-"providers" to execute all the steps involved in the ROCK's build process. At
+Rockcraft is distributed as a snap. For packing new rocks, it makes use of
+"providers" to execute all the steps involved in the rock's build process. At
 the moment, the supported providers are LXD and Multipass.
 
 Requirements

docs/how-to/index.rst

@@ -22,4 +22,4 @@ adapt the steps to fit your specific requirements.
    Install a custom package slice <install-slice>
    Publish a slice definition <publish-slice>
    Convert an entrypoint to a Pebble layer <convert-to-pebble-layer>
-   Publish a ROCK to a registry <publish-a-rock.rst>
+   Publish a rock to a registry <publish-a-rock.rst>

docs/how-to/install-slice.rst

@@ -50,7 +50,7 @@ If you wanted to test it with Chisel alone, you could now simply run
 You should end up with a folder named "my-custom-openssl-fs" containing a few
 folders, amongst which there would be ``./usr/bin/openssl``.
 
-**To install the custom package slice into a ROCK though**, you need to use
+**To install the custom package slice into a rock though**, you need to use
 Rockcraft!
 
 Start by initialising a new Rockcraft project:
@@ -79,7 +79,7 @@ install from a custom Chisel release. If the desired slice definitions are
 already upstream, then you can simply use ``stage-packages``, as demonstrated
 in :ref:`here <chisel-example>`.
 
-Build your ROCK with:
+Build your rock with:
 
 .. literalinclude:: code/install-slice/task.yaml
     :language: bash
@@ -159,5 +159,5 @@ The output of the Docker command will be OpenSSL's default help message:
     <... many more lines of output>
 
 
-And that's it! You've now built your own ROCK from a custom Chisel release.
+And that's it! You've now built your own rock from a custom Chisel release.
 Next step: share your slice definitions file with others!

docs/how-to/publish-a-rock.rst

@@ -1,4 +1,4 @@
-Publish a ROCK to a registry
+Publish a rock to a registry
 ============================
 
 Prerequisites
@@ -8,10 +8,10 @@ Prerequisites
 - Docker installed (https://docs.docker.com/get-docker/)
 
 
-Push a ROCK to Docker Hub
+Push a rock to Docker Hub
 -------------------------
 
-The output of ``rockcraft pack`` is a ROCK in its oci-archive archive format.
+The output of ``rockcraft pack`` is a rock in its oci-archive archive format.
 
 ..  code-block:: bash
 

docs/how-to/rockcraft-pack-action.rst

@@ -4,17 +4,17 @@ How to use Rockcraft's GitHub Action
 Within your GitHub repository, make sure you have
 `GitHub Actions enabled <https://docs.github.com/en/actions/quickstart>`_.
 
-Navigate to ``.github/workflows``, open the YAML file where you want the ROCK
+Navigate to ``.github/workflows``, open the YAML file where you want the rock
 build to take place, and add the following steps:
 
 .. literalinclude:: code/rockcraft-pack-action/rockcraft-pack.yaml
     :language: yaml
 
 Commit and push the changes. This will trigger a new workflow run using
-Rockcraft to pack your ROCK based on the ``rockcraft.yaml`` file at your
+Rockcraft to pack your rock based on the ``rockcraft.yaml`` file at your
 project's root.
 
-To learn how to publish this ROCK outside the GitHub build environment and how
+To learn how to publish this rock outside the GitHub build environment and how
 to pass additional input parameters to this action, please refer to the
 `action's
 documentation <https://github.com/canonical/craft-actions#rockcraft-pack>`_.