Merge branch 'main' into renovate/main-bugfixes

.github/workflows/release-drafter.yaml

@@ -0,0 +1,16 @@
+name: Release Drafter
+
+on:
+  push:
+    # branches to consider in the event; optional, defaults to all
+    branches:
+      - main
+
+jobs:
+  update_release_draft:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Release Drafter
+        uses: release-drafter/release-drafter@v6.1.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-publish.yaml

@@ -0,0 +1,72 @@
+name: Release
+on:
+  push:
+    tags:
+      # These tags should be protected, remember to enable the rule:
+      # https://github.com/canonical/starbase/settings/tag_protection
+      - "[0-9]+.[0-9]+.[0-9]+"
+
+permissions:
+  contents: write
+
+jobs:
+  source-wheel:
+    runs-on: [self-hosted, jammy]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Fetch tag annotations
+        run: |
+          # Note: we fetch the tags here instead of using actions/checkout's "fetch-tags"
+          # because of https://github.com/actions/checkout/issues/1467
+          git fetch --force --tags --depth 1
+          git describe --dirty --long --match '[0-9]*.[0-9]*.[0-9]*' --exclude '*[^0-9.]*'
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          check-latest: true
+      - name: Build packages
+        run: |
+          pip install build twine
+          python3 -m build
+          twine check dist/*
+      - name: Upload pypi packages artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: pypi-packages
+          path: dist/
+  pypi:
+    needs: ["source-wheel"]
+    runs-on: [self-hosted, jammy, amd64]
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+    steps:
+      - name: Get packages
+        uses: actions/download-artifact@v4
+        with:
+          name: pypi-packages
+          path: dist/
+      - name: Publish to pypi
+        # Note: this action uses PyPI's support for Trusted Publishers
+        # It needs a configuration on the PyPI project - see:
+        # https://docs.pypi.org/trusted-publishers/adding-a-publisher/#github-actions
+        uses: pypa/gh-action-pypi-publish@release/v1
+  github-release:
+    needs: ["source-wheel"]
+    runs-on: [self-hosted, jammy]
+    steps:
+      - name: Get pypi artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: pypi-packages
+      - name: Release
+        uses: softprops/action-gh-release@v2
+        with:
+          # Generate release notes on the new GH release
+          generate_release_notes: true
+          # Add wheel and source tarball
+          files: |
+            *.whl
+            *.tar.gz

.readthedocs.yaml

@@ -5,25 +5,30 @@
 # Required
 version: 2
 
-build:
-  os: ubuntu-24.04
-  tools:
-    python: "3.10"
-  jobs:
-    post_checkout:
-      - git fetch --tags --depth 1  # Also fetch tags
-      - git describe --always       # Useful for debugging
-
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
   builder: dirhtml
   fail_on_warning: false
 
-# Optionally set the version of Python
-# and requirements required to build your docs
-python:
-  install:
-    - requirements: requirements-dev.txt
-    - method: pip
-      path: .[docs]
+# Optionally build your docs in additional formats such as PDF
+# formats:
+#  - pdf
+#  - epub
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_checkout:
+      - git fetch --tags --unshallow  # Also fetch tags
+      - git describe --always         # Useful for debugging
+    post_system_dependencies:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    create_environment:
+      - uv venv "${READTHEDOCS_VIRTUALENV_PATH}"
+    install:
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv sync --frozen --extra docs

charmcraft/services/provider.py

@@ -126,10 +126,12 @@ def instance(
             try:
                 # Use /root/.cache even if we're in the snap.
                 instance.execute_run(
-                    ["rm", "-rf", "/root/snap/charmcraft/common/cache"]
+                    ["rm", "-rf", "/root/snap/charmcraft/common/cache"], check=True
                 )
+                instance.execute_run(["mkdir", "-p", "/root/.cache"], check=True)
                 instance.execute_run(
-                    ["ln", "-s", "/root/.cache", "/root/snap/charmcraft/common/cache"]
+                    ["ln", "-s", "/root/.cache", "/root/snap/charmcraft/common/cache"],
+                    check=True,
                 )
                 yield instance
             finally:

docs/conf.py

@@ -45,6 +45,7 @@
 html_context = {
     "product_page": "github.com/canonical/charmcraft",
     "github_url": "https://github.com/canonical/charmcraft",
+    "github_issues": "https://github.com/canonical/charmcraft/issues",
     "discourse": "https://discourse.charmhub.io",
 }
 

docs/howto/build-guides/pack-a-hooks-based-charm-with-charmcraft.rst

@@ -5,7 +5,8 @@ How to pack a hooks-based charm with Charmcraft
 
     Introduced in Charmcraft 1.4
 
-    See first: :external+ops:ref:`turn-a-hooks-based-charm-into-an-ops-charm`
+    See first: :external+ops:ref:`Ops | Turn a hooks-based charm into an ops charm
+    <turn-a-hooks-based-charm-into-an-ops-charm>`
 
 Suppose you have a legacy hooks-only charm, for example, `tiny-bash
 <https://github.com/erik78se/tiny-bash>`_, which you can clone with:

docs/howto/build-guides/select-platforms.rst

@@ -12,7 +12,7 @@ See the :doc:`Platforms reference </reference/platforms>` for more information.
 Select an OS
 ------------
 
-The :ref:`charmcraft-yaml-base` key in ``charmcraft.yaml`` defines the operating
+The project's :ref:`charmcraft-yaml-base` key defines the operating
 system and version on which a charm can build and run. Supported OSs
 vary by both the version of Charmcraft and the version of `Juju`_.
 
@@ -27,8 +27,8 @@ The general syntax for defining a distribution and series is to use
 Select one build and one target architecture
 --------------------------------------------
 
-The following ``charmcraft.yaml`` snippet will define a charm that both builds and
-runs on Ubuntu 24.04 LTS, only on an AMD64 architecture:
+The following snippet defines a charm that both builds and runs on Ubuntu 24.04 LTS,
+only on an AMD64 architecture:
 
 .. code-block:: yaml
 
@@ -61,7 +61,7 @@ Select one build architecture and target all architectures
 ----------------------------------------------------------
 
 When crafting a charm that contains only architecture-independent code,
-set ``build-for: [all]``. For example, the following ``charmcraft.yaml`` snippet
+set ``build-for: [all]``. For example, the following project file snippet
 packs a single charm on an AMD64 host while declaring support for any architecture:
 
 .. code-block:: yaml
@@ -100,7 +100,7 @@ Select multiple build and target architectures
 Charms may contain architecture-specific code and thus need separate artifacts
 for each. You can declare multiple architectures in the ``platforms`` key,
 which instructs Charmcraft to build a charm for each of them as a set. For
-example, you could use the following snippet in ``charmcraft.yaml`` to build
+example, you could use the following snippet in your project to build
 for both AMD64 and 64-bit RISC-V:
 
 .. code-block:: yaml
@@ -137,7 +137,7 @@ Select different architectures for building and running
 -------------------------------------------------------
 
 A charm may require cross-compilation to build. To create a charm for a
-different architecture, use the following ``charmcraft.yaml`` snippet:
+different architecture, use the following snippet:
 
 .. code-block:: yaml
 
@@ -160,13 +160,13 @@ Select multiple OS releases
 ---------------------------
 
 The resulting ``.charm`` file packed by charmcraft can only run on a single OS release
-or ``base``, using ``charmcraft.yaml`` nomenclature. A ``charmcraft.yaml`` can use
-multi-base syntax to create a set of charms, each for a different base. To do this, the
-base is defined in each platform entry instead of being defined with the
-top-level ``base`` and ``build-base`` keys.
+or ``base``, using ``charmcraft.yaml`` nomenclature. A project file can use multi-base
+syntax to create multiple ``.charm`` files, each for a different base. To do this, the
+base is defined in each platform entry instead of being defined with the top-level
+``base`` and ``build-base`` keys.
 
 To build a charm for Ubuntu 22.04 LTS and a charm for Ubuntu 24.04 LTS, use the
-following ``charmcraft.yaml`` snippet which uses :ref:`multi-base
+following snippet which uses :ref:`multi-base
 notation<reference-platforms-multi-base>`:
 
 .. code-block:: yaml

docs/howto/manage-12-factor-app-charms.rst

@@ -24,11 +24,10 @@ Use ``charmcraft init`` and specify the relevant profile:
 
   charmcraft init --profile <profile>
 
-Charmcraft automatically creates ``charmcraft.yaml``,
-``requirements.txt`` and source code for the charm in your
-current directory. You will need to check ``charmcraft.yaml``
-and ``README.md`` to verify that the charm's name and
-description are correct.
+Charmcraft automatically creates a ``charmcraft.yaml`` project file, a
+``requirements.txt`` file and source code for the charm in your current directory. You
+will need to check the project file and ``README.md`` to verify that the charm's name
+and description are correct.
 
     See also: :ref:`ref_commands_init`
 
@@ -99,10 +98,9 @@ token for a service. Add the configuration in ``charmcraft.yaml``:
         also available in the Flask variable ``app.config`` without
         the ``FLASK_`` prefix.
 
-            See also:
-            :external+ops:ref:`How to add configuration to a charm <manage-configurations>`,
-            `Configuration Handling --
-            Flask Documentation <https://flask.palletsprojects.com/en/3.0.x/config/>`_
+            See also: :external+ops:ref:`Ops | Manage configurations
+            <manage-configurations>`, `Configuration Handling -- Flask Documentation
+            <https://flask.palletsprojects.com/en/3.0.x/config/>`_
 
     .. group-tab:: Django
 
@@ -155,7 +153,7 @@ Manage relations for a 12-factor app charm
 ------------------------------------------
 
 A charm integration can be added to your charmed 12-factor app by providing
-the integration and endpoint definition in ``charmcraft.yaml``:
+the integration and endpoint definition in your project file:
 
 .. code-block:: yaml
 
@@ -168,7 +166,7 @@ Here, ``<endpoint name>`` corresponds to the endpoint of the application with wh
 you want the integration, and ``<endpoint interface name>`` is the endpoint schema
 to which this relation conforms. Both the ``<endpoint name>`` and
 ``<endpoint interface name>`` must coincide with the structs defined in the
-``charmcraft.yaml`` file of that particular application's charm. The key ``optional``
+pfoject file of that particular application's charm. The key ``optional``
 with value ``False`` means that the charm will get blocked and stop the services if
 the integration is not provided.
 
@@ -185,7 +183,7 @@ use to configure your 12-factor application.
 For example, if you wish to integrate your 12-factor application with PostgreSQL
 (`machine <https://charmhub.io/postgresql>`_ or
 `k8s <https://charmhub.io/postgresql-k8s>`_
-charm), add the following endpoint definition to ``charmcraft.yaml``:
+charm), add the following endpoint definition to your project file:
 
 .. code-block:: yaml
 
@@ -224,7 +222,7 @@ Manage secrets for a 12-factor app charm
 
 A user secret can be added to a charm and all the keys and values
 in the secret will be exposed as environment variables. Add the secret
-configuration option in ``charmcraft.yaml``:
+configuration option in your project file:
 
 .. code-block:: yaml