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?
| @@ -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.
| 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.
| 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"?
This adds howto guides to switch from the charm plugin to the python and poetry plugins.