Plan usability suggestions

[qubitrenegade]

per @christophermaier request, this issue related to my forum post of the same topic.

To summarize:

• add plan_url variable
• add long/short description variables
• Provide method to "slurp" README into long description.

Basically taking a page out of the Chef Supermarket... ah hem... cookbook... (dodges tomatoes) I think it would be beneficial to have a plan_url variable or similar that facilitates linking to the plan source. Many of the core plans have really good READMEs that provide additional usage but sometimes finding them isn't easy. It's really not a good user experience to google "habitat" which tends to make finding plan source a pain. Having a link similar to supermarket that will take you directly to the plan would be extremely useful. This should probably be an optional parameter if for instance someone is not releasing the plan as opensource, we wouldn't want to penalize them and prevent them from building. I've been adding a link to the github page in my descriptions, but that just seems like a kludgey solution.

Along those lines, it would also be really useful to have a long/short description. The short description could make a good item to be parsed/indexed by search engines and the long description could provide additional usage instructions (again, similar to how Supermarket operates).

And, since many people are already writing good READMEs, having the ability to just slurp the README into the long description would also be immensely useful so I don't essentially have to maintain two READMEs.

In my head cannon, the plan_url would be a link on the sidebar of bldr and the long_description could be included in the main page where the plan/default.toml are displayed.

[christophermaier]

In addition to affecting plan syntax, we'd want to tweak the package display pages in Builder to take advantage of this new data.

[rsertelon]

Also, there was an issue to include the README in bldr UI here: https://github.com/habitat-sh/builder/issues/23

[themightychris]

I brought this same issue up in slack a while back and we had settled on using pkg_plan_source as the var, I started using it in some of my plans but haven't stuck to it very rigidly. Would be great for something to be officially implemented and produce a github link in the bldr web UI

[qubitrenegade]

And while we're at it, what about updating the documentation on dockerhub when plans are published/exported to docker hub?

:+1: for pkg_plan_source since it seems to follow the same format of existing pkg_ variables.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. We value your input and contribution. Please leave a comment if this issue still affects you.

[qubitrenegade]

I think this is still a worthy topic of discussion...

On Fri, Apr 3, 2020 at 12:40 AM stale[bot] [email protected] wrote:

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. We value your input and contribution. Please leave a comment if this issue still affects you.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/habitat-sh/habitat/issues/5108#issuecomment-608258671, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADSBHCLM6U2PJRW3UATKTZDRKWAFZANCNFSM4FBC5X6Q .

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. We value your input and contribution. Please leave a comment if this issue still affects you.