docs: add howto guides for switching from the charm plugin #1967
Conversation
This adds howto guides to switch from the charm plugin to the python and poetry plugins.
lengau
force-pushed
the
work/1913/CRAFT-3425/howto
branch
from
95567bd
to
1347d86
Compare
|
Gave this a go here: jnsgruk/zinc-k8s-operator#288 Might be worth including a section about using I guess they could also use Edit: lots of failed integration tests when I changed to this; will investigate. |
|
Heh. The python plugin doesn't seem to have included any Edit: switched to the Alas, no dice on deploying, though... |
| Ensure a recent enough version of ``pip`` | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| The ``python`` plugin requires at least pip 22.3, released in October 2022. If the |
There was a problem hiding this comment.
pip 22.3, released in October 2022
Rather than mentioning the date, can we link to https://pypi.org/project/pip/22.3 instead?
There was a problem hiding this comment.
We can link there as well, but the date is also useful because it gives them a good idea as to whether their base distribution is going to have a new enough pip out of the box. For example, CentOS 7 and Ubuntu Jammy won't because they were all released before then (so they'll need to follow this), but Ubuntu Noble does. I don't want to list specific bases because that just gives us a treadmill of bases to update.
| @@ -0,0 +1,107 @@ | |||
| .. _howto-migrate-to-poetry: | |||
|
|
|||
| Migrate from the ``charm`` plugin to Poetry | |||
There was a problem hiding this comment.
For consistency with existing docs and docs best practices, we should use the form Charm plugin and Python plugin.
| .. code-block:: yaml | ||
|
|
||
| parts: | ||
| my-charm: # This can be named anything you want |
There was a problem hiding this comment.
A morsel for thought: we generally discourage the use of comments in bash, but I'm not sure where configs fit in, since we encourage users to copy them. As a general principle it's better to use the doc to explain things.
There was a problem hiding this comment.
We use comments pretty heavily in our config file templates. In this case, the goal of the comment is to counter something that's a fairly common misconception amongst charm authors (that the part name needs to be named the plugin name or the actual charm name) without having an aside about it, since that's out of scope for the document.
| plugin: poetry | ||
| source: . | ||
|
|
||
| Ensure a recent enough version of ``pip`` and ``poetry`` |
There was a problem hiding this comment.
| Ensure a recent enough version of ``pip`` and ``poetry`` | |
| Select compatible versions of ``pip`` and ``poetry`` |
| The ``poetry`` plugin requires at least pip 22.3, released in October 2022. If the | ||
| charm's base uses an older version of pip, a newer version can be installed in the | ||
| build environment using a dependency part. Likewise, a charm may require a newer | ||
| version of poetry than is available in the distribution's repositories. The following |
There was a problem hiding this comment.
| version of poetry than is available in the distribution's repositories. The following | |
| version of Poetry than is available in the distribution's repositories. The following |
|
|
||
| .. note:: | ||
| This is useful and encouraged, though not mandatory, for keeping track of | ||
| library dependencies (see below). For an example, see |
There was a problem hiding this comment.
| library dependencies (see below). For an example, see | |
| library dependencies, as covered in the next section. For an example, see |
| Unlike the ``charm`` plugin, the ``poetry`` plugin does not install the dependencies | ||
| for included charmlibs. If any of the charm libraries used have PYDEPS, these will | ||
| need to be added to the charm's dependencies, potentially as their own | ||
| `dependency group <dependency groups>`_. |
| Migrate from the ``charm`` plugin to the ``python`` plugin | ||
| ========================================================== | ||
|
|
||
| The ``python`` Charmcraft plugin offers a faster, stricter means of packing an operator |
There was a problem hiding this comment.
Charmcraft plugin
Do we need to be this specific here? "Python Charmcraft plugin" tripped me up as a phrase.
There was a problem hiding this comment.
Yes, because it works slightly differently from the Rockcraft plugin, the Snapcraft plugin, etc.
| python-requirements: | ||
| - requirements.txt # Or whatever your requirements file is called. | ||
|
|
||
| Ensure a recent enough version of ``pip`` |
There was a problem hiding this comment.
| Ensure a recent enough version of ``pip`` | |
| Select a compatible version of ``pip`` |
| ========================================================== | ||
|
|
||
| The ``python`` Charmcraft plugin offers a faster, stricter means of packing an operator | ||
| charm with a virtual environment. This guide shows how to migrate from a charm using |
There was a problem hiding this comment.
"packing with" is slightly ambiguous, so we might want to take special care with how we express this. If I'm understanding this correctly, could we say "packing a virtual environment inside an operator charm"?
There was a problem hiding this comment.
The suggested language has implications that I'm not sure we want. The actual operator charm is their code - we're packing a charm package that includes the virtual environment.
This adds howto guides to switch from the charm plugin to the python and poetry plugins.