docs: refresh icon guidance

docs/.custom_wordlist.txt

@@ -134,6 +134,7 @@ URIs?
 URL
 utils
 uv
+validator
 Valkey
 venv
 VM's

docs/howto/add-an-icon.rst

@@ -0,0 +1,104 @@
+.. meta::
+    :description: How to create, validate, and add an icon to a charm's Charmhub page.
+                  Includes a demo of using Inkscape to draw the icon.
+
+.. _manage-icons:
+.. _how-to-add-an-icon:
+
+Add an icon to Charmhub
+=======================
+
+Creating a custom icon for your charm is a great way to make it stand out on Charmhub.
+This guide works through creating, validating, and adding an icon to your charm's
+Charmhub page.
+
+
+Install prerequisites
+---------------------
+
+You can create the icon with any vector graphics editor, but this guide works through
+the process with Inkscape. If you're following along step by step, `install Inkscape
+<https://inkscape-manuals.readthedocs.io/en/latest/installing-on-linux.html>`__.
+
+Next, right-click on the following link to save the `icon template
+<https://assets.ubuntu.com/v1/fc0260eb-icon.svg>`__ to your machine. Leave the file name
+as ``icon.svg``.
+
+
+Draw the icon in Inkscape
+-------------------------
+
+Open Inkscape and load the icon template you downloaded in the previous step.
+
+To change the icon's background color, start by pressing :kbd:`Ctrl` + :kbd:`Shift` +
+:kbd:`L` and clicking on :guilabel:`BACKGROUND` in the resulting tab.
+
+.. figure:: images/add-an-icon/layer-select.png
+    :alt: Layer selection interface in the Inkscape editor
+
+With the background layer selected, press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`F` to open
+the Fill and Stroke interface. You can then select a color for the background.
+
+.. figure:: images/add-an-icon/color-select.png
+    :alt: Fill and stroke selection interface in Inkscape
+
+Next, go back to the layer selection window and select the :guilabel:`PLACE LOGO HERE`
+layer. If you already have a vector image icon, drag it into this layer. If you have
+a bitmap image, you'll need to convert it into a vector file first.
+
+If you don't have an existing logo, you can use the drawing tools in Inkscape to create
+one from scratch.
+
+Once everything is to your liking, rename this layer to something more meaningful, like
+:guilabel:`LOGO` or :guilabel:`ICON`.
+
+.. figure:: images/add-an-icon/import-logo.png
+    :alt: Draw something
+
+Once you're happy with your icon, press :kbd:`Ctrl` + :kbd:`Shift` + :kbd:`S` and save
+the file as ``icon.svg`` in the directory containing your charm's project file.
+
+
+Validate the icon
+-----------------
+
+Go to the `Charmhub icon validator <https://charmhub.io/icon-validator>`_ and upload
+your icon to check for any issues with its file type or dimensions. If you used the
+provided template, this should pass without any issues.
+
+To fix issues related to the icon's size, go back into Inkscape, press :kbd:`Ctrl` +
+:kbd:`Shift` + :kbd:`D`, and set the height and width to 100 pixels.
+
+
+.. _how-to-pack-the-icon-in-the-charm:
+
+Pack the icon in the charm
+--------------------------
+
+For the icon to be displayed on Charmhub, it needs to be packed into the final charm
+artifact. Ensure that the ``icon.svg`` file is present in the directory containing your
+charm's project file.
+
+If your charm's main part uses the Charm plugin, the icon will be packed in the final
+charm by default.
+
+For every other plugin, you need to explicitly add the ``icon.svg`` file to the charm
+by adding a new part using the :ref:`craft_parts_dump_plugin` to your project file.
+
+.. code-block:: yaml
+    :caption: charmcraft.yaml
+
+    parts:
+      icon:
+        plugin: dump
+        source: .
+        stage:
+          - icon.svg
+
+The next time you :ref:`publish the charm <publish-a-charm>` to its default track's
+``stable`` channel, the icon will be displayed on Charmhub. Charmhub only updates the
+charm's metadata on releases to the ``stable`` channel.
+
+If you aren't ready for a ``stable`` release, you can add the icon by releasing and
+then rolling back a revision. However, it's generally recommended you wait until
+the charm is ready for a true ``stable`` release.

docs/howto/index.rst

@@ -39,7 +39,7 @@ publish it to Charmhub, and manage its releases.
 - :ref:`how-to-build-remotely`
 - :ref:`manage-the-current-charmhub-user`
 - :ref:`manage-names`
-- :ref:`manage-icons`
+- :ref:`how-to-add-an-icon`
 - :ref:`manage-charm-revisions`
 - :ref:`manage-tracks`
 - :ref:`manage-channels`
@@ -84,6 +84,6 @@ update a charm to the new base:
     manage-revisions
     manage-channels
     manage-tracks
-    manage-icons
+    add-an-icon
     Migrate plugins <migrate-plugins/index>
     Migrate bases <migrate-bases/index>

docs/howto/migrate-plugins/charm-to-poetry.rst

@@ -89,10 +89,10 @@ from all loaded charmlibs.
 Include extra files
 -------------------
 
-A Poetry plugin only includes the contents of the ``src`` and ``lib`` directories
-as well as the generated virtual environment. If other files such as a charm's icon
-were previously included from the main directory, stage them in the charm in a new part
-that uses the :ref:`craft_parts_dump_plugin`:
+A Poetry plugin only includes the contents of the ``src`` and ``lib`` directories as
+well as the generated virtual environment. Other files, such as the
+:ref:`icon-svg-file`, are no longer included by default and need to be explicitly packed
+in the charm with a new part that uses the :ref:`craft_parts_dump_plugin`.
 
 .. code-block:: yaml
     :caption: charmcraft.yaml

docs/howto/migrate-plugins/charm-to-python.rst

@@ -110,10 +110,10 @@ that generates ``requirements.txt``.
 Include extra files
 -------------------
 
-The Python plugin only includes the contents of the ``src`` and ``lib`` directories
-as well as the generated virtual environment. If other files such as a charm's icon
-were previously included from the main directory, stage them in the charm in a new part
-that uses the :ref:`craft_parts_dump_plugin`:
+The Python plugin only includes the contents of the ``src`` and ``lib`` directories as
+well as the generated virtual environment. Other files, such as the
+:ref:`icon-svg-file`, are no longer included by default and need to be explicitly packed
+in the charm with a new part that uses the :ref:`craft_parts_dump_plugin`.
 
 .. code-block:: yaml
     :caption: charmcraft.yaml

docs/howto/migrate-plugins/charm-to-uv.rst

@@ -161,10 +161,10 @@ Likewise, optional dependencies under the ``pyproject.toml`` key
 Include extra files
 -------------------
 
-The uv plugin only includes the contents of the ``src`` and ``lib`` directories
-as well as the generated virtual environment. If other files such as a charm's icon
-were previously included from the main directory, stage them in the charm in a new part
-that uses the :ref:`craft_parts_dump_plugin`:
+The uv plugin only includes the contents of the ``src`` and ``lib`` directories as well
+as the generated virtual environment. Other files, such as the :ref:`icon-svg-file`, are
+no longer included by default and need to be explicitly packed in the charm with a new
+part that uses the :ref:`craft_parts_dump_plugin`.
 
 .. code-block:: yaml
     :caption: charmcraft.yaml

docs/redirects.txt

@@ -6,6 +6,7 @@
 
 "howto/set-up-charmcraft.rst" "howto/manage-charmcraft.rst"
 "howto/install-charmcraft.rst" "howto/manage-charmcraft.rst"
+"howto/manage-icons.rst" "howto/add-an-icon.rst"
 "howto/manage-parts.rst" "reference/parts/index.rst"
 "tutorial/write-your-first-kubernetes-charm-for-a-django-app.rst" "tutorial/kubernetes-charm-django.rst"
 "tutorial/write-your-first-kubernetes-charm-for-a-flask-app.rst" "tutorial/kubernetes-charm-flask.rst"

docs/reference/files/icon-svg-file.rst

@@ -1,3 +1,6 @@
+.. meta::
+    :description: Reference for the ``icon.svg`` file, including its required dimensions, best practices, and examples.
+
 .. _icon-svg-file:
 
 ``icon.svg`` file
@@ -44,23 +47,8 @@ Examples
 Including the file
 ------------------
 
-If your file is not in your project directory but not included in the charm, you can
-use the :ref:`craft_parts_dump_plugin` to include this file in your charm.
-
-.. dropdown:: Example
-
-    This example is the :ref:`charmcraft-yaml-key-parts` key of a project file that uses
-    the :ref:`craft_parts_poetry_plugin` to build a charm, augmented to add the charm's
-    ``icon.svg`` file.
-
-    .. code-block:: yaml
+If your charm's main part uses the Charm plugin, the ``icon.svg`` file is packed in the
+final charm by default if included in the same directory as your project file.
 
-        parts:
-          my-charm:
-            plugin: poetry
-            source: .
-          icon:
-            plugin: dump
-            source: .
-            stage:
-              - icon.svg
+If your charm's main part uses the Python, Poetry, or uv plugin, the ``icon.svg`` file
+must be :ref:`packed in the charm manually <how-to-pack-the-icon-in-the-charm>`.