docs: add version information for tools in the charming ecosystem #2231
Conversation
…ion based on other choices.
|
@dwilding I've made an initial attempt at this, as we discussed in our meeting. Could you please look over it and suggest alternative ways of presenting the information and/or other improvements? No hurry at all - I probably won't have time to come back to this until January. |
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive version compatibility documentation to the Ops framework explanation section, helping charm developers navigate version dependencies across the charming ecosystem. The documentation consolidates scattered version information into a single, accessible reference.
- Adds a new documentation page explaining version relationships between bases, Python, Juju, Ops, Charmcraft, and Pebble
- Provides support lifecycle information for Juju and Ops releases, including EOL dates
- Updates the explanation index to include the new versions page
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/explanation/versions.md | New documentation page providing version compatibility matrices and support lifecycle information for the charming ecosystem |
| docs/explanation/index.md | Adds reference to the new versions documentation in the toctree |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| |---------|--------|--------------|-------------| | ||
| | [Ops 1.x](https://github.com/canonical/operator/blob/main/SECURITY.md) | 🔴 EOL | 2020-10-31 | 2024-04-26 | | ||
| | [Ops 2.x](https://github.com/canonical/operator/blob/2.23-maintenance/SECURITY.md) | 🟡 Active | 2023-01-25 | 2026-07-30 | | ||
| | [Ops 3.x](https://github.com/canonical/operator/blob/main/SECURITY.md) | 🟢 Active | 2025-07-02 | 2027-01-01 | |
There was a problem hiding this comment.
The End of Life date for Ops 3.x appears inconsistent with the stated support policy. The documentation states that major versions are "supported with security fixes for one year from the latest release", but the dates show a release on 2025-07-02 with EOL on 2027-01-01, which is approximately 1.5 years. Please clarify whether this is correct or if the EOL date should be 2026-07-02.
| | [Ops 3.x](https://github.com/canonical/operator/blob/main/SECURITY.md) | 🟢 Active | 2025-07-02 | 2027-01-01 | | |
| | [Ops 3.x](https://github.com/canonical/operator/blob/main/SECURITY.md) | 🟢 Active | 2025-07-02 | 2026-07-02 | |
There was a problem hiding this comment.
The bit that Copilot can't see here is when the last release was. Maybe I should add that to the table, since you do have to have it in order to do the calculation.
However, maybe we shouldn't show an EOL for 3.x? If we never do another 3.x release then in theory it is the date that's in the table. But it will be annoying to update that with each release (the release script could handle it I suppose), and realistically it's going to keep moving, which is a bit weird for a EOL.
As per the discussion in Gothenburg, I think we need to reconsider Ops versioning this cycle. I think we tentatively agreed that we would pick an LTS version of 3.x towards the end of the cycle, and when we do that we'll have a clearer story here.
If you can only use Ops 2.x with 20.04, maybe our "just move to 3.x" isn't good enough and we have to actually make 2.23 an LTS that lasts until April 2035?
There was a problem hiding this comment.
Our latest thinking is to list the latest Ops release for each major version, eg 3.5, along with the corresponding release and EOL dates
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
Sorry @tonyandrewmeyer, I haven't had a chance to look at this yet. Shall we have a look during our doc time tomorrow? |
No rush at all, looking at it some time over the next three weeks while I'm off and talking about it in January would totally be fine. But can do in our doc time today also, if that works better. |
dwilding
left a comment
dwilding
left a comment
There was a problem hiding this comment.
Thanks for collecting this all together 🙂
From our discussion: We acknowledge that Explanation is not the ideal place to put this Diataxis-wise, but Reference has a different use in the Ops docs. We can revisit as we think about the overall distribution of charming content across different sites.
| (tool-versions)= | ||
| # Tool versions | ||
|
|
||
| In deciding which version of tools to use within the charming ecosystem, the base is the key constraint. Once the base is selected, use the latest supported version of each tool whenever possible. |
There was a problem hiding this comment.
Minor: I'd probably make this more active. Something like:
| In deciding which version of tools to use within the charming ecosystem, the base is the key constraint. Once the base is selected, use the latest supported version of each tool whenever possible. | |
| When you're deciding which version of tools to use within the charming ecosystem, the base is the key constraint. Once you have selected the base, use the latest supported version of each tool whenever possible. |
|
|
||
| In deciding which version of tools to use within the charming ecosystem, the base is the key constraint. Once the base is selected, use the latest supported version of each tool whenever possible. | ||
|
|
||
| Charms should only support deployment on the LTS versions of Juju that are not yet end-of-life. |
There was a problem hiding this comment.
I think this should go somewhere else (best practices?) or probably fine to remove it, as LTS and end-of-life already imply this meaning
| Charms should only support deployment on the LTS versions of Juju that are not yet end-of-life. |
|
|
||
| ## Find tool versions by base | ||
|
|
||
| Choosing the base or bases that your charm will support in turn selects the versions of Juju, Ops, and Charmcraft that you should use, and the default version of Python available. |
There was a problem hiding this comment.
No need to introduce the table, I'd say
| Choosing the base or bases that your charm will support in turn selects the versions of Juju, Ops, and Charmcraft that you should use, and the default version of Python available. |
|
|
||
| | Base | Python | Juju | Ops | Charmcraft | | ||
| |------|----------------|---------------|--------------|-------------------| | ||
| | 18.04 (Bionic Beaver) | [3.6](https://documentation.ubuntu.com/ubuntu-for-developers/reference/availability/python/) | [2.9](https://documentation.ubuntu.com/juju/latest/releasenotes/juju_2.9.x/) | 1.x | [2.x](https://documentation.ubuntu.com/charmcraft/latest/explanation/bases/) | |
There was a problem hiding this comment.
We figured it's more logical to link version numbers to release notes, then provide source/reference links outside the table
|
|
||
| Charms should only support deployment on the LTS versions of Juju that are not yet end-of-life. | ||
|
|
||
| ## Find tool versions by base |
There was a problem hiding this comment.
The titles don't need to be how-to style. E.g., "Tool versions by bases" or even "Bases" if that doesn't feel too terse to you
|
|
||
| ## Find your Pebble version from the Juju version | ||
|
|
||
| Each version of Juju uses a specific version of Pebble. To determine which Pebble features are available to you, look up the Pebble version from the Juju version. |
There was a problem hiding this comment.
How about strengthening the first sentence. Something like:
| Each version of Juju uses a specific version of Pebble. To determine which Pebble features are available to you, look up the Pebble version from the Juju version. | |
| Each version of Juju provides a fixed version of Pebble. To determine which Pebble features are available to you, look up the Pebble version from the Juju version. |
| |---------|--------|--------------|-------------| | ||
| | [Ops 1.x](https://github.com/canonical/operator/blob/main/SECURITY.md) | 🔴 EOL | 2020-10-31 | 2024-04-26 | | ||
| | [Ops 2.x](https://github.com/canonical/operator/blob/2.23-maintenance/SECURITY.md) | 🟡 Active | 2023-01-25 | 2026-07-30 | | ||
| | [Ops 3.x](https://github.com/canonical/operator/blob/main/SECURITY.md) | 🟢 Active | 2025-07-02 | 2027-01-01 | |
There was a problem hiding this comment.
Our latest thinking is to list the latest Ops release for each major version, eg 3.5, along with the corresponding release and EOL dates
| - 🟡 Active: Supported but approaching EOL | ||
| - 🔴 EOL: End of life, no longer supported |
There was a problem hiding this comment.
Suggest changing 🔴 to ❌ for better colour-blind accessibility. We also thought that Active is worth keeping, but change the name and symbol. The name could be something like "Upgrade soon". Maybe 🔔 for the icon? Not sure!
3 participants
Adds a new page to the explanation section of the docs (maybe this should be reference, but I think in the Ops docs, reference should stick to being API references, and it's not a tutorial or how-to -- if there was a charming doc site, then it might fit as reference there...).
There are three main sections:
The intention is to make it easier to find this information. Most of it is available elsewhere (I couldn't find the Juju/base data and had to manually test that) but it's scattered around and not necessarily in documentation. For example, you can get the Pebble version from the Juju version by going to the Juju repository, moving to the appropriate tag, and then looking for Pebble in the go.mod file. However, that's not very user-friendly or intuitive, and we do get charmers occasionally asking that question.
Explore the raw data.
Preview