Information provided for a charm does not correspond to the selected revision
Opened this issue · 9 comments
As I understand it, the information displayed in a charm's tabs (Description, Resources, Libraries, Configure, Actions, etc) is borne out of the revision pointing at the charm's default-release key, which is usually the latest/stable channel. This means that when an alternate channel is selected in the Charmhub all the above information can potentially become inaccurate. Some charms differ significantly between channels, OpenStack charms in particular - where tracks are used extensively.
I was prompted to file this bug due to the impact it has on the documentation that we are being encouraged to add to the charms.
We can explore feasibility of allowing the /info API endpoint (which powers the pages you refer to) to accept a "channel" parameter and exposing the information of the revision released in that channel, rather than the default one.
This would have to be done on the charmhub.io backend, and would need a bunch of internal wiring to fetch this info from the revision service which is an extra API call so we need to consider performance impact and etc. It's definitely not a frontend-only issue, it needs backend support as well.
We might be able to hack similar functionality in, with creative use of the refresh API, but I'd rather reserve refresh for actual "will result on a charm install, update or download" operations.
One big use case is having any docs submitted to a Discourse channel, which is the recommended method, to be called upon by Charmhub so that the correct docs are displayed.
I understand that, after speaking with @Roadmaster out of band, as long as the docs: key (in a charm's metadata.yaml file) points to the correct Discourse URL then it should be possible. The key will just now need to be made unique to some parameter, like charm revision. Note that what I'm personally interested in is one documentation set per track.
I also know now that documentation hosted on Discourse is not a backend concern. All the backend does is give the Discourse page URL to the frontend and the latter handles the rest. Hence, assistance from the web team may be needed.
It appears that I was wrong with respect to the tabs. That is, the Actions tab displayed is accurate according to the selected channel. However, my use case involves Discourse-based docs. Should this not also be possible if each track is backed by a unique git branch?
It is possible to get specific channel contents in default-release by using a channel param, e.g: &channel=edge in the request to /info BUT the channel-map content is restricted to the selected channel.
Please let us know if this works for you to implement the channel switching for the requested data via the dropdown.
Cheers
We already request the info endpoint with the channel parameter. And then, to obtain the docs property, we parse the metadata.yaml from this field in the API response default-release.revision.metadata-yaml.
@verterok, is this the right field when using the channel parameter? I don't see any other field to obtain the metadata.yaml for specific tracks.
@jkfran that's the correct field 👍
So, things should be working. Could be a caching related bug?
The cache seems to be fine because our URLs also include the ?channel=edge so the cache will be per track.
I think the issue might be because this parameter in the URL is not persistent when clicking around.
I believe the issue here is that if you switch the track (stable -> edge) you see the same set of docs. It does not make sense to create a modified clone of the docs for each track in discourse. So, I would suggest we recommend using a single documentation for all tracks but add annotations that detail what version something was added or removed to the package.