31. Set up URL redirects to user docs

In the output of the pre-refresh-check action, charm-refresh will display a URL to the charm’s user documentation for in-place refreshes. More info: User experience

URL format

charm-refresh will generate the URL using this format:

https://charmhub.io/{charm_name}/docs/refresh/{charm_version}

{charm_name} will be replaced with the value of charm_name from 18. Instantiate refresh class.

{charm_version} will be replaced with the charm compatibility version of the charm code that the pre-refresh-check action is run on (i.e. the charm code version that the user will be refreshing from). The / character in the charm compatibility version will not be URL-encoded.

Example URL

https://charmhub.io/postgresql-k8s/docs/refresh/16/1.19.0

Redirect target

This URL must be redirected to user documentation that provides instructions for how to refresh from this version (e.g. 16/1.19.0) to all versions that support refreshing from that version.

At the time this version (e.g. 16/1.19.0) is released, it will not be possible to know all of the future versions that will support refreshing from that version

Set up redirects

Community charm developers

Canonical staff

These instructions assume that all charm compatibility versions for a track share the same redirect target. For more specific redirects (i.e. if the refresh instructions are different for some versions), refer to IS' documentation on the sites.yaml format.

Clone https://code.launchpad.net/canonical-mojo-specs
Open website-content-cache/production/sites.yaml

Under charmhub.io key → locations key, add a redirect

Example redirect

charmhub.io:
  locations:
    /postgresql-k8s/docs/refresh/16/: (1)
      backend-inter-time: 5s
      cache-validity: '200 307 1h'
      extra-config: ['return 307 https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/16/how-to/refresh/'] (2)

1	Replace `postgresql-k8s` with the charm name in metadata.yaml. Replace `16` with the track the charm is released to
2	Replace `https://canonical-charmed-postgresql-k8s.readthedocs-hosted.com/16/how-to/refresh/` with the Redirect target

Use a 307 HTTP response status code to indicate a temporary redirect so that the redirect target can be changed in the future (if versions in the same track need different refresh instructions)

Commit changes

Example commit message

Add Charmhub redirect for postgresql-k8s refresh user docs

Open a merge request
Ask in https://chat.canonical.com/canonical/channels/is for the merge request to be reviewed