Merge branch 'main' into extension/block-on-missing

Author: alithethird

.github/workflows/schema.yaml

@@ -0,0 +1,67 @@
+name: Schema
+on: [pull_request]
+
+env:
+  CHARMCRAFT_JSON: schema/charmcraft.json
+
+jobs:
+  diff-schema:
+    runs-on: ubuntu-22.04
+
+    steps:
+      - name: Checkout rockcraft
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv with caching
+        id: setup-uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-suffix: ${{ steps.runner-info.outputs.cache-hash }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Run generator script
+        run: |
+          uv run --frozen --no-dev --extra apt-jammy \
+            python tools/schema.py > generated_schema.json
+
+      - name: Check with stored schema
+        run: |
+          test -f $CHARMCRAFT_JSON &&
+          diff generated_schema.json $CHARMCRAFT_JSON
+
+  validate-schema:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Charmcraft
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install ajv cli
+        run: npm install -g ajv-cli
+
+      - name: Run ajv
+        run: |
+          # Don't fail immediately if one validation fails
+          EXIT_CODE=0
+          for proj_file in tests/spread/smoketests/basic/charmcraft*; do
+            if ! ajv validate -s $CHARMCRAFT_JSON \
+              -d $proj_file \
+              --strict=false --spec=draft2020; then
+              EXIT_CODE=1
+            fi
+          done
+          exit $EXIT_CODE

Makefile

@@ -117,3 +117,7 @@ else
 	brew install multipass
 	brew install skopeo
 endif
+
+.PHONY: schema
+schema: install-uv
+	uv run tools/schema.py > schema/charmcraft.json

charmcraft/models/project.py

@@ -1115,7 +1115,7 @@ def _populate_platforms(cls, platforms: dict[str, Any]) -> dict[str, Any]:
         return platforms
 
 
-Charm = BasesCharm | PlatformCharm
+Charm = PlatformCharm | BasesCharm
 
 
 class Bundle(CharmcraftProject):

docs/howto/manage-revisions.rst

@@ -7,6 +7,7 @@ Manage charm revisions
 
     <!--As opposed to resource revisions. (Or bundle revisions, but that's being phased out.)-->
 
+
 Create a charm revision
 -----------------------
 
@@ -15,6 +16,7 @@ Charmhub (unless you're uploading the exact same file again).
 
     See more: :ref:`publish-a-charm`
 
+
 View the existing charm revisions
 ---------------------------------
 
@@ -23,20 +25,30 @@ followed by the name of the charm.
 
     See more: :ref:`ref_commands_revisions`
 
+
 Promote a charm revision to a better risk level
 -----------------------------------------------
 
-To promote a charm revision to a higher-ranking risk level, use the GitHub
-``promote-charm`` action.
+To promote a charm revision to a more stable risk level, run
+:literalref:`charmcraft promote<ref_commands_promote>` with flags specifying the current
+and desired channels. For example, to promote a charm from the ``candidate`` channel to
+the ``stable`` channel, you would run:
+
+.. code-block:: bash
+
+    charmcraft promote --from-channel=candidate --to-channel=stable
 
-    See more: `GitHub | canonical/charming-actions/promote-charm
-    <https://github.com/canonical/charming-actions/tree/2.6.0/promote-charm>`_
+If you are looking to promote charm revisions in your CI workflow, the same result can
+be achieved with the `Charmhub Promotion
+<https://github.com/canonical/charming-actions/tree/main/promote-charm>`_ GitHub action.
+Note that this GitHub action resides in a separate repository and is therefore
+maintained separately from Charmcraft.
 
 .. collapse:: Example outcome
 
-    For example, in the (partial) output of juju info mongodb below, revision 100 has
-    been promoted from ``3.6/edge`` through ``3.6/beta`` and ``3.6/candidate`` all the
-    way to ``3.6/stable``. (The up arrow next to ``3.6/beta`` indicates that that
+    For example, in the following output of ``juju info mongodb``, revision 100
+    has been promoted from ``3.6/edge`` through ``3.6/beta`` and ``3.6/candidate`` all
+    the way to ``3.6/stable``. (The up arrow next to ``3.6/beta`` indicates that that
     channel has been closed and, if you try ``juju deploy --channel 3.6/beta``, what
     you'll get is the next higher-ranking risk level of the same track, that is,
     ``3.6/candidate``.)

docs/reference/files/charmcraft-yaml-file.rst

@@ -937,7 +937,7 @@ at least one ``requires`` integration with ``container`` scope.
 .. collapse:: Example
 
     .. literalinclude:: charmcraft-sample-charm.yaml
-        :start-at: storage: # Possible storage for the charm
+        :start-at: storage:  # Possible storage for the charm
         :end-before: subordinate:
 
 

docs/tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst

@@ -8,6 +8,10 @@ PostgreSQL and need to deploy it. In a traditional setup, this can be
 quite a challenge, but with Charmcraft you’ll find yourself packaging
 and deploying your Django application in no time.
 
+
+Introduction
+------------
+
 In this tutorial we will build a Kubernetes charm for a Django
 application using Charmcraft, so we can have a Django application up and
 running with Juju. Let’s get started!
@@ -24,16 +28,18 @@ This tutorial should take 90 minutes for you to complete.
    can be easily deployed, configured, scaled, integrated, etc.,
    on any Kubernetes cluster.
 
+
 What you’ll need
-----------------
+~~~~~~~~~~~~~~~~
 
 -  A local system, e.g., a laptop, with amd64 or arm64 architecture
    which has sufficient resources to launch a virtual machine with 4
    CPUs, 4 GB RAM, and a 50 GB disk.
 -  Familiarity with Linux.
 
+
 What you’ll do
---------------
+~~~~~~~~~~~~~~
 
 Create a Django application. Use that to create a rock with
 ``rockcraft``. Use that to create a charm with ``charmcraft``. Use that
@@ -381,6 +387,7 @@ respond with something similar to
    If you are not on the ``amd64`` platform, the name of the ``.charm``
    file will be different for you.
 
+
 Deploy the Django application
 -----------------------------
 
@@ -516,12 +523,22 @@ Now you can open a new tab and visit http://django-hello-world. The
 Django app should respond in the browser with
 ``The install worked successfully! Congratulations!``.
 
-Add an initial app
-------------------
+
+The development cycle
+---------------------
+
+So far, we have worked though the entire cycle, from creating an application to
+deploying it. But now -- as in every real-world case -- we will go through the
+experience of iterating to develop the application, and deploy each iteration.
+
+
+Add a "Hello, world" app
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this iteration, we'll add a greeting app that returns a ``Hello, world!`` greeting.
 
 The generated Django application does not come with an app, which is why
-we had to initially enable debug mode for testing. Let’s add a greeting
-app that returns a ``Hello, world!`` greeting. We will need to go back
+we had to initially enable debug mode for testing.  We will need to go back
 out to the ``/django-hello-world`` directory where the rock is and enter
 into the ``/django_hello_world`` directory where the Django application
 is. Let’s add a new Django app:
@@ -556,6 +573,10 @@ Open the ``django_hello_world/urls.py`` file and edit the imports for
        path("admin/", admin.site.urls),
    ]
 
+
+Update the rock
+~~~~~~~~~~~~~~~
+
 Since we’re changing the application we should update the version of the
 rock. Go back to the ``/django-hello-world`` directory where the rock is
 and change the ``version`` in ``rockcraft.yaml`` to ``0.2``. The top of
@@ -593,8 +614,13 @@ Now let’s pack and upload the rock using similar commands as before:
     :end-before: [docs:repack-update-end]
     :dedent: 2
 
-Now we can deploy the new version of the Django application from the
-``/charm`` directory using:
+
+Redeploy the charm
+~~~~~~~~~~~~~~~~~~
+
+We'll redeploy the new version with ``juju refresh``.
+
+In the ``/charm`` directory, run:
 
 .. literalinclude:: code/django/task.yaml
     :language: bash
@@ -618,8 +644,8 @@ inside the Multipass VM. Either way, the Django application should respond
 with ``Hello, world!``.
 
 
-Enable a configuration
-----------------------
+Provide a configuration
+-----------------------
 
 To demonstrate how to provide a configuration to the Django application,
 we will make the greeting configurable. We will expect this
@@ -632,6 +658,10 @@ with:
 .. literalinclude:: code/django/views_greeting_configuration.py
    :language: python
 
+
+Update the rock (again)
+~~~~~~~~~~~~~~~~~~~~~~~
+
 Increment the ``version`` in ``rockcraft.yaml`` to ``0.3`` such that the
 top of the ``rockcraft.yaml`` file looks similar to the following:
 
@@ -667,6 +697,10 @@ Let’s pack and upload the rock:
     :end-before: [docs:repack-2nd-update-end]
     :dedent: 2
 
+
+Update the charm
+~~~~~~~~~~~~~~~~
+
 Change back into the charm directory using ``cd charm``.
 
 The ``django-framework`` Charmcraft extension supports adding
@@ -683,7 +717,8 @@ the end of the ``charmcraft.yaml`` file:
    replaced by ``_``. A ``DJANGO_`` prefix will also be added as a
    namespace for app configurations.
 
-We can now pack and deploy the new version of the Django app:
+We can now pack a new version of the charm, and then deploy it once more with ``juju
+refresh``:
 
 .. literalinclude:: code/django/task.yaml
     :language: bash