-
Notifications
You must be signed in to change notification settings - Fork 71
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add howto guides for switching from the charm plugin #1967
base: main
Are you sure you want to change the base?
Conversation
This adds howto guides to switch from the charm plugin to the python and poetry plugins.
95567bd
to
1347d86
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Very clear!
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...
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for putting these together!
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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>`_. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Unspecified link.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.