Make Rock-on links consistent

phillxnet commented 8 years ago

When clicking on the names of Rock-ons I think it should link to the upstream project, not the docker maintainers page. This way users will get to see what they are to install not the details of the packager / docker container. However it would also be nice to acknowledge the origin of the docker container so I propose to normalize this info by having the subtitle of each Rock-on name via a "by" entry, link to the docker maintainer. This is already done in for example the current Plex Rock-on but in that same case we don't link to the Plex site via the name.

Proposal summary:

Names link to upstream projects ie as with Syncthing currently.
subtitles (below names) identify that the system is "Continous File Synchronization" but optionally adds "docker image by ......".

This way we cover both options where the more technical can search for the docker maintainer but the general title link serves the initial upstream link to the main project.

phillxnet commented 5 years ago

Can we have input on this idea as I still think it stands up. Plus it would good to get this expected behaviour in place sooner rather than later. Especially as our current list of Rock-ons is now quite large.

phillxnet commented 5 years ago

Including a quote from 'closed as duplicate' issue by @seffyroff towards this discussion:

"Right now browsing the Catalog of Rockons is very sparse. I don't know the source of the Rockon (whose Plex comtainer is that) without looking in Github at the contents of the .json. I don't know the version number, or last update version - these are important :)"

Thanks @seffyroff .

FroggyFlox commented 5 years ago

Hi @phillxnet ,

I think that's a good idea and does make more sense as it allows the user to get more information on what this Rock-on actually does. I also agree that we need to keep a good description of the image's particularities especially as we now have more and more projects with multiple Rock-ons (Owncloud for instance). Should we push for a more homogenous use of the "description: object in the JSON file, with some sort of quick template? We also have the "version" object that could be used further to help alleviate this problem.

phillxnet commented 5 years ago

I think all descriptions should contain example share names so it just makes for an easier experience. So definitely that. I think all the early ones did have this and it got missed as we went on. Also keen on formalising within the json as then all new rock-ons can be vetted to contain this and we can programatically extract with more reliability. Potentially properly offering a Web-UI component that reflects this element as an auto create if non existent option with a warning if it already exists. This would also make redundant the bespoke inclusion of this info within a description.

As to the version element. Yes that one has seen some attention; see: [Enhancement - Rockons] Add current Rock-on version on Rock-ons table https://github.com/rockstor/rockstor-core/issues/1636 where @MFlyer also submitted a pr: https://github.com/rockstor/rockstor-core/pull/1637 but as per the discussion in that pr it was closed as requiring more design effort. I see the version component as for our json variant use (see the discussion). That way we can more elegantly deal with otherwise potentially breaking changes in a file. The discussion also touches on retrieving docker version info. Easiest for now is to surface our existing links to upstream project and docker image origin so we have at least that. Ergo this issue. Maybe the docker image extraction difficult referenced in that pr discussion has since been resolved. In which case great, we could surface that.

Apologies if I've drifted here.

coleberhorst commented 5 years ago

If you could decide on a template, I'd be more than happy to fix them all.

phillxnet commented 5 years ago

@coleberhorst Thanks for the offer. Much appreciated. I'll pop in a little more here.

We may have to take a successive approximation approach hear as the Rock-on system is a work in progress and some what of a moving target. And given @FroggyFlox is the main 'mover' on that system the timing of this across the board change would best be their call.

In summary I initially thought

A link to upstream project: the main title seems to make sense here.
A new 'subtitle' entry that is explicitly for the image / images used.

So on that basis we also need a companion issue in rockstor-core once we are agreed on what elements to include where. And given each Rock-on generally serves as an 'application provider' the link we currently have per Rock-on:

"website": should reflect that application, ie Plex linking to plex.tv for example.

Then we have an additional per container top level entry json element that links to the page for the "image": entry it lives under; I.e.,

"image-website": should link to image used, ie "https://hub.docker.com/r/linuxserver/plex/"

As for our existing plex json.

This can then help to surface the number of docker images within a Rock-on and which ones are used. That way users can quickly research the 'discreet' elements of a Rock-on and keep things simple yet transparent. Also we compartmentalise the need to reference (within user text for example) exactly which docker image/images a Rock-on is based on.

I'll leave this call to @FroggyFlox.

So I think it's best we first formalise json entries for this as it forces structure that we then don't have to enforce on pull requests after the fact as it will be obviously in the json structure itself and then we can display as appropriate. With a view to blanking on these new "image-website" entries if they are not found (older rock-on jsons). Which is where this issue comes in I suspect, ie bringing each and every Rock-on 'up to a new format'.

Comments welcome.

coleberhorst commented 5 years ago

I like the inclusion of the image, I think that the rockon catalog should be as visual as possible. Maybe even a future update to the visuals of the rockon tab that displays each one as mostly an icon. I'd always thought like a 4 columns x infinite rows grid of rockons would be cool for a future update. This template/ consistency issue seems like an important first step to making the rockons more accessible.

FroggyFlox commented 5 years ago

Thanks @phillxnet and @coleberhorst for all the ideas, and thanks @coleberhorst for volunteering in deploying what will come up to all rock-ons :+1: . There's a lot to unpack here so I'll try to organize myself as best as I can and cut them in separate, more manageable parts. I apologize in advance if I miss an important point stated above. Note that I also will try to always think about the different options with a "complex" rock-on in mind--involving several containers and/or having one or more alternative rock-on already existing--in order to put these options to test (mentally for now).

I see three different points that need to be decided:

What information to display.
How to display that information.
How to make sure this information is provided with a new rock-on submission.

1. Information to display

Rock-on name: should correspond to the project name. Using the title seems like a no-brainer, indeed.
Image(s) name(s): with link to the docker hub (or docker store).
Share(s) name(s).
Description: free text, using the current "description" object in the json definition. For projects with multiple rock-ons available, try to emphasis the need for highlighting the advantages and limitations of each rock-on to help the user decide which one fits her/his needs the best.
Support for "Add storage" option? I'm undecided about that, but that's an option.
Logo: use project's logo.

2. How to display

Rock-on name: Using the title seems like a no-brainer, indeed.
Image(s) name(s): Use a new subtitle line? We can use a container name (image name) format, such as plex-linuxserver.io (linuxserver/plex) for the current Plex rock-on. Fortunately we should be able to create links automatically as the docker hub urls follows a clear naming convention (I love when that's the case). This means we shouldn't need to create and ask for a new object in the json file. Of note, this subtitle entry may be inline--rather than each image on separate line--to keep the space used to a minimum in the case of multi-containers rock-ons.
Share(s) name(s): Use a fixed, templated sentence like: "This rock-on needs X shares: <list of comma-separated volume labels from json>". This wouldn't need any extra line as everything can be pulled from the existing json.
Description: Same as currently used.
Support for "Add storage" option? Maybe we could use @coleberhorst's idea of a tag or a little glyphicon for that, placed next to the rock-on title.
Logo: we already have an "icon" object in the json.

We also need to think of how to make all of this fit. This may represent a lot of extra information that would result in a very heavy page/list of available rock-ons. @coleberhorst's idea of grid of icons (as a choose-able display option) is a good option here, but it would require an overall rewrite of how the list of available rock-ons is displayed, and thus take some time to be implemented. I do like that idea, though, so would you (@coleberhorst) open an issue for that on the rockstore-core repo?

Alternatively, we could require a new json object called "running_title" corresponding to a very brief description of the rock-on function(s), with a character limit of 80-100, for instance. All other information would then be shown to the user by clicking a "more details" link (or the running title itself) in an accordeon-style (similar to how a network connection's details are displayed by clicking its name in the "System > Network" page).

I also have been entertaining the idea of categorizing all rock-ons to simplify navigation among all available rock-ons.

3. Ensure all information is provided upon submission

This one is the most unclear point to me, as I can't seem to decide which option would be best in my opinion:

If we make any of the new json objects proposed above mandatory, we can still avoid breaking all existing install by ensuring first that all rock-ons json comply before rolling out the code using it, but this would apply only to rock-ons in the official rockon-registry... this would likely to result in broken rock-ons list for local rock-ons, isn't it?
The main advantage of point 1 above is that all PR would have to have this information as any problem would be revealed by errors when reviewing/testing. Could such compliance be enforced at the PR level, however, with some automatic testing? I'm thinking about the mention of Github apps you made in another post, @phillxnet, do you think this could be a good fit for something like that? (maybe it was your idea from the beginning, I can't seem to find that post now, I apologize) @phillxnet, I believe you already were thinking of a solution for that, as per your quoted phrases below, but I'm confused by the second sentence and do not fully see what you have in mind.

Also keen on formalising within the json as then all new rock-ons can be vetted to contain this and we can problematically extract with more reliability. Potentially properly offering a Web-UI component that reflects this element as an auto create if non existent option with a warning if it already exists.

I'll keep this post updated as we figure out the little details.

phillxnet commented 5 years ago

@FroggyFlox Thanks for your details consideration / thought on this one.

as per:

this would likely to result in broken rock-ons list for local rock-ons, isn't it?

Not necessarily, hence my comment that we 'deal' with missing new elements such as your suggested "running_title" element. If it's not there we have a blank line. It's not the end of the world and it would make obvious which rock-ons need 'mending'.

2. I'm thinking about the mention of Github apps you made in another post, @phillxnet, do you think this could be a good fit for something like that?

Definitely. I'm actually working towards backend testing as we speak (slowly mind as have found some bugs on my way).

I also have been entertaining the idea of categorizing all rock-ons to simplify navigation among all available rock-ons.

Yes I was wondering about this. We could possibly provide a sort / category based on the provider by parsing the docker image and paring, for example, all the linuxserver.io ones together. Just a idea.

As per @FroggyFlox observation, we do need to keep each issue as focused as we can. And baby steps that are completed get us further along than giant re-writes that never get completed. So I agree that the pic matrix would be nice but we can do a lot to improve what we already have as per the suggestions so far.

Well done people this little issue is getting quite a work out.

coleberhorst commented 5 years ago

Ok opened an issue for the rockstor-core for the grid idea: https://github.com/rockstor/rockstor-core/issues/2015

rockstor / rockon-registry