Decouple README from release

cwjohnston commented 4 years ago

Expected behavior

Documentation on a asset page can be updated without cutting a new release

Current behavior

Any documentation changes require a new Github Release.

Possible solution

Use release README by default, but allow asset owners and admins to manually override the displayed readme by pointing at a specific commit on the project repository.

Context

Many plugins are under documented and hard to consume. Efforts are under way to standardize documentation but publishing those changes to Bonsai requires superfluous version bumps and otherwise presents a bottleneck and poor UX for plugin developers.

jspaleta commented 4 years ago

I think we can actually put this in the bonsai.yml actually.

provide a readme_url override specifically for each release. normally it would be the same for every release... but it could be different for an experimental release if needed.

Might even be able to point to a readme markdown outside of github...this way.

jspaleta commented 4 years ago

to give bonsai admins access we'd need to expose this as a Manage asset option.

but i think ideally encoding this in the .bonsai.yml makes the most sense, the maintainers of the asset will have the best sense as to what they want to do here.

mbiang commented 4 years ago

Workflow:

Add a top level "overrides" block in bonsai.yaml.
Under overrides, support "readme_url", which must point to a valid markdown file.
During asset compilation, if "readme_url" is present in "overrides", then we should download the markdown file at "readme_url", and use this file instead of the README in the repository root.
We should ensure that the content type of the file at "readme_url" is markdown. If not, we should raise a compilation error.

pzupan commented 4 years ago

The application is now looking for an overrides entry in bonsai.yml. Here is an example:

---
description: "#{repo}"
overrides:
- readme_url: "https://github.com/sensu-plugins/sensu-plugins-cpu-checks/blob/master/README.md"
builds:
- platform: "alpine"

cwjohnston commented 4 years ago

As I understand it, the proposed implementation still relies on the readme_url override to be part of the .bonsai.yml in a commit included in a Github Release.

If that is correct, I do not understand how the proposed implementation solves for the expected behavior, i.e.

Documentation on a asset page can be updated without cutting a new release

pzupan commented 4 years ago

Once the override has been included in the bonsai.yml file, it points to a markdown file of your choice. When you make edits to that markdown, and recompile the asset, it updates the readme on Bonsai without a new release of the asset.

mbiang commented 4 years ago

@pzupan - If a user provides a standard Github HTML URL, we should translate it to the raw file URL. For example:

https://github.com/jspaleta/sensu-plugins-redis/blob/master/README.md should translate to https://raw.githubusercontent.com/jspaleta/sensu-plugins-redis/master/README.md

jspaleta commented 4 years ago

So after talking a bit more concerning the original request. There's a need to take this further and implement this as an override that can be applied via the web-ui under the manage asset pull down so the existing releases can be overridden.

@pzupan Now that we have the override logic in place can this be further extended so the override can be populated at the entire asset level via the web-ui?

Strawman precedent would work like this: Top priority: use repository wide override set via manage asset web-ui if set Fallback priority: use release specific bonsai.yml override if set Final Fallback: Readme in tagged release

jspaleta commented 4 years ago

i change my mind it would be better to have this ordering: Top priority:use release specific bonsai.yml override if set Fallback priority:use repository wide override set via manage asset web-ui if set Final Fallback: Readme in tagged release

that way you could have a release specific override for a special release if you absolutely needed it.

Its a corner case for sure.

jspaleta commented 4 years ago

Looks like its working:

Example:https://bonsai-asset-index-staging.herokuapp.com/assets/jspaleta/sensu-plugins-redis/

In this asset I have a repo wide override set to the postgres readme set using the new UI.

In the versions 4.0.0-jef.1 and 4.0.0-pre show the postgres override readme In the versions 4.0.0-jef.3 and 4.0.0-jef.2 the .bonsai.yml has an explicit override set and it takes precedent over the one set repo wide.

sensu / bonsai