docs: convert howtos to rst

docs/common/craft-parts

@@ -0,0 +1 @@
+/home/dora/git/charmcraft/.tox/docs/lib/python3.12/site-packages/craft_parts_docs/craft-parts

docs/howto/index.rst

@@ -0,0 +1,22 @@
+.. _how-to-guides:
+How-to guides
+=============
+
+.. toctree::
+   :maxdepth: 2
+
+   Manage the charmcraft CLI <manage-the-charmcraft-cli>
+   Manage charms <manage-charms>
+   Manage charms (12-factor apps) <manage-12-factor-app-charms>
+   Manage extensions <manage-extensions>
+   Manage resources <manage-resources>
+   Manage libraries <manage-libraries>
+   Manage parts <manage-parts>
+   Manage the current Charmhub user <manage-the-current-charmhub-user>
+   Manage names <manage-names>
+   Manage revisions <manage-revisions>
+   Manage channels <manage-channels>
+   Manage tracks <manage-tracks>
+   Manage icons <manage-icons>
+   Misc <misc/index>
+   Manage bundles <manage-bundles>

docs/howto/manage-bundles.rst

@@ -0,0 +1,40 @@
+.. manage-charm-bundles:
+How to manage charm bundles
+===========================
+
+   See first: `Juju \| Bundle <https://juju.is/docs/juju/bundle>`__
+
+.. important::
+   Starting with 1 Jan 2025, bundles are being phased out.
+
+
+Create a bundle
+---------------
+
+To create a bundle, create a ``<bundle>.yaml`` file with your desired configuration.
+
+  See more: :ref:`file-bundle-yaml`
+
+.. tip::
+   If you don't want to start from scratch, export the contents of your model to a ``<bundle>.yaml`` file via ``juju export-bundle --filename <bundle>.yaml`` or download the ``<bundle>.yaml`` of an existing bundle from Charmhub. See more: `Juju \| How to compare and export the contents of a model to a bundle <https://juju.is/docs/juju/manage-models#heading--compare-and-export-the-contents-of-a-model-to-a-bundle>`_.
+
+
+Pack a bundle
+-------------
+
+To pack a bundle, in the directory where you have your ``bundle.yaml``
+file (and possibly other files, e.g., a ``README.md`` file), create a
+``charmcraft.yaml`` file suitable for a bundle (at the minimum:
+``type: bundle``), then run ``charmcraft pack`` to pack the bundle. The
+result is a ``.zip`` file.
+
+   See more: :ref:`ref_commands_pack`
+
+Publish a bundle on Charmhub
+----------------------------
+
+The process is identical to that for a simple charm except that, at the
+step where you register the name, for bundles the command is
+``register-bundle``.
+
+   See more: :ref:`publish-a-charm`

docs/howto/manage-channels.rst

@@ -0,0 +1,86 @@
+.. _manage-channels:
+How to manage channels
+======================
+
+Create a channel
+----------------
+
+When you register a name on Charmhub, that automatically creates 4 channels, all with track ``latest`` but with different risk levels, namely, ``edge``, ``beta``, ``candidate``, ``stable``, respectively.
+
+   See more: :ref:`register-a-name`
+
+.. raw:: html
+
+   <!--
+   A charm channel consists of three pieces, in this order: <track>/<risk>/<branch>.
+
+   The <risk> refers to one of the following risk levels:
+
+       stable: (default) This is the latest, tested, working stable version of the charm.
+       candidate: A release candidate. There is high confidence this will work fine, but there may be minor bugs.
+       beta: A beta testing milestone release.
+       edge: The very latest version - expect bugs!
+
+
+   When you register, you get a track called `latest` with all the usual risk levels. So, you get all of:
+
+   latest/stable
+   latest/candidate
+   latest/beta
+   latest/edge
+
+   This counts as 4 separate channels. They're created implicitly. (They're only _opened_ if you release a revision to them.)
+
+   The track is what you request a guardrail and create a new of (not the channel).
+
+   Later on, if you specify a channel, you get:
+   - An implicit stable risk, if you don't declare a risk.
+   - An implicit empty branch, if you don't declare a branch.
+   -->
+
+View the available channels
+---------------------------
+
+To view a charm’s channels on Charmhub, run ``charmcraft status``
+followed by the name of the charm. E.g.,
+
+.. code:: text
+
+   $ charmcraft status my-awesome-charm
+   Track    Channel    Version    Revision
+   latest   stable     -          -
+            candidate  -          -
+            beta       0.1        1
+            edge       ↑          ↑
+
+(The above output shows 4 channels, all of which have the same track,
+``latest``, but different risk levels, namely, ``edge``, ``beta``,
+``candidate``, and ``stable``.)
+
+   See more: :ref:`ref_commands_status`
+
+Customise a channel’s track
+---------------------------
+
+You can request a track guardrail and create a track.
+
+  See more: :ref:`manage-tracks`
+
+Open a channel
+--------------
+
+A channel is opened implicitly when you release a revision to it.
+
+Close a channel
+---------------
+
+A channel is opened when you release a revision to that channel. Before
+that, the channel is created but not opened. When you’re closing a
+channel, e.g., latest/candidate, that means that any deployment requests
+that go there will be forwarded to the next most stable risk, e.g., for
+beta, latest/stable. If you close stable, you can no longer deploy or
+update from that, unless you release again to that channel (because
+releasing opens the channel).
+
+If you add a branch, closing that branch will forward people to the same
+track and risk, without a branch.