docs: add explanation, reference, and how to for bases

Signed-off-by: Callahan Kovacs <callahan.kovacs@canonical.com>

docs/explanation/bases.rst

@@ -0,0 +1,71 @@
+Bases
+=====
+
+.. include:: /reuse/bases-intro.rst
+
+``base`` and ``build-base``
+---------------------------
+
+If ``build-base`` is defined , then the ``build-base`` will determine the
+environment where the snap is built.
+
+If ``build-base`` is not defined, the ``base`` will determine the
+environment where the snap is built.
+
+For example, ``base: core24`` will build a snap in a Ubuntu 24.04 environment
+with the ``core24`` snap installed. Stage packages will be installed from the
+24.04 repository.
+
+``build-base: devel`` will build a snap using the upcoming Ubuntu release in
+development. This is defined as the Ubuntu image with the ``devel`` alias in
+the `Ubuntu buildd image server`_.
+
+Base snaps
+----------
+
+A base snap is a special kind of snap that provides a run-time environment with
+a cardinal set of libraries that are common to most applications. They’re
+transparent to users, but they need to be considered and specified when building
+a snap.
+
+Mounting
+--------
+
+The base snap mounts itself as the root filesystem within a snap's runtime
+environment. When an application runs, the base's library paths are searched
+directly after the paths for that snap.
+
+Choosing a base
+---------------
+
+``core24`` is the recommended base for most snaps. Much like choosing a
+distribution base for a project or server, the best base for an application is
+dependent on an application’s requirements and which plugins or extensions a
+base supports. If there are specific dependencies that cannot be easily met
+then the next newest base ``core22`` is a valid and supported alternative.
+
+Snapcraft `extensions`_ enable bundling a set of common requirements into a
+snap, such as for running KDE Plasma or GNOME applications. Extensions support
+specific bases. See `supported extensions`_ for a list of which extensions
+support which bases.
+
+.. _base-snap-explanation:
+
+Building a base snap
+--------------------
+
+While uncommon, developers can build their own base snap. They are responsible
+for maintenance and updates, in particular:
+
+* bases need to be built from stable packages
+* ABI compatibility cannot broken (ie. never replace symbols or libraries, and
+  be strict)
+* security updates must be proactive
+
+Base snaps can be either bootable or non-bootable. The former needs to include
+``systemd`` while the latter can be leaner.
+
+
+.. _`Ubuntu buildd image server`: https://cloud-images.ubuntu.com/buildd/daily/
+.. _`extensions`: https://snapcraft.io/docs/snapcraft-extensions
+.. _`supported extensions`: https://snapcraft.io/docs/supported-extensions

docs/explanation/index.rst

@@ -7,6 +7,7 @@ Explanation
    :maxdepth: 1
 
    architectures
+   bases
    remote-build
    /common/craft-parts/explanation/filesets
    /common/craft-parts/explanation/parts

docs/howto/bases.rst

@@ -0,0 +1,151 @@
+Bases
+=====
+
+.. include:: /reuse/bases-intro.rst
+
+How to use a base
+-----------------
+
+The base a snap will use is defined in the snap's `snapcraft.yaml`_.
+
+To use the ``core24`` base for a snap:
+
+.. code-block:: yaml
+
+   base: core24
+
+
+How to migrate to a newer base
+------------------------------
+
+See `migrating bases`_ for details on migrating to a newer base.
+
+
+How to use a deprecated base
+----------------------------
+
+The latest release of Snapcraft does not support older bases. Prior major
+Snapcraft releases are supported and can be installed from Snapcraft's
+`tracks`_.
+
+See :ref:`base snaps<base-snap-reference>` for a list of which Snapcraft
+major releases support a particular base.
+
+See `Snapcraft and ESM`_ for details on support for deprecated bases.
+
+``core18``
+^^^^^^^^^^
+
+To build ``core18`` snaps, install snapcraft 7 from the *7.x* track:
+
+.. code-block:: shell
+
+   $ snap install snapcraft --channel 7.x
+
+``core``
+^^^^^^^^
+
+To build ``core`` snaps, install snapcraft 4 from the *4.x* track:
+
+.. code-block:: shell
+
+   $ snap install snapcraft --channel 4.x
+
+
+The base snap mounts itself as the root filesystem within your snap such that
+when your application runs, the base’s library paths are searched directly
+after the paths for your specific snap.
+
+How to develop supported and deprecated bases
+---------------------------------------------
+
+When developing snaps using supported and deprecated bases at the same time,
+developers must use different versions of Snapcraft. There are a few options:
+
+Refresh channels
+^^^^^^^^^^^^^^^^
+
+Switch between Snapcraft releases by refreshing channels. ``snapd`` retains the
+previously installed snap, so refreshing between two channels should not
+require re-downloading Snapcraft.
+
+.. code-block:: shell
+
+   $ snap refresh snapcraft --channel 7.x
+   $ snap refresh snapcraft --channel 8.x
+
+Parallel installs
+^^^^^^^^^^^^^^^^^
+
+Multiple instances of Snapcraft can be installed via ``snapd``'s experimental
+parallel install feature. See the `Parallel installs`_ documentation for
+details.
+
+.. code-block:: shell
+
+   $ snap install snapcraft snapcraft_7 --channel 7.x
+   $ snap install snapcraft snapcraft_8 --channel 8.x
+   $ snapcraft_8 pack
+
+Containers
+^^^^^^^^^^
+
+Isolated development environments allow using different versions of Snapcraft
+simultaneously.
+
+`Snapcraft rocks`_ are the recommended way to build snaps in a container:
+
+
+How to bootstrap a base snap
+----------------------------
+
+The ``build-base`` keyword is used to bootstrap and create new bases.
+
+To bootstrap the ``core26`` base snap, use the following ``snapcraft.yaml``
+snippet:
+
+.. code-block:: yaml
+
+   name: core26
+   type: base
+   build-base: core24
+
+This snippet will do the following:
+
+* ``name: core26`` sets the snap's name to ``core26``.
+* ``type: base`` creates a base snap.
+* ``build-base: core24`` builds the snap inside an Ubuntu 24.04 build
+  environment.
+* ``base`` cannot be set in the ``snapcraft.yaml`` file
+
+
+.. _kernel-snap-how-to:
+
+How to build a kernel snap for interim releases
+-----------------------------------------------
+
+The ``build-base`` keyword is used to build kernel snaps for interim Ubuntu
+releases.
+
+To build a kernel snap targeting the Ubuntu 24.10 release, use the following
+``snapcraft.yaml`` snippet:
+
+.. code-block:: yaml
+
+   name: pc-kernel
+   type: kernel
+   base: core24
+   build-base: ubuntu@24.10
+
+This snippet will do the following:
+
+* create a kernel snap for Ubuntu 24.10
+* build the snap inside an Ubuntu 24.10 build environment
+* use the ``core24`` feature set and ``snapcraft.yaml`` schema
+
+
+.. _`Snapcraft and ESM`: https://snapcraft.io/docs/snapcraft-esm
+.. _`Snapcraft rocks`: https://github.com/canonical/snapcraft-rocks
+.. _`migrating bases`: https://snapcraft.io/docs/migrating-bases
+.. _`parallel installs`: https://snapcraft.io/docs/parallel-installs
+.. _`tracks`: https://snapcraft.io/docs/channels#heading--tracks

docs/howto/index.rst

@@ -7,5 +7,6 @@ How-to guides
    :maxdepth: 1
 
    architectures
+   bases
    /common/craft-parts/how-to/include_files
    /common/craft-parts/how-to/override_build