Rh-che: Documentation with architectural insights about plugin brokers

[ibuziuk]

Documentation is supposed to be published on eclipse.org website - https://www.eclipse.org/che/docs/che-7/index.html

Existing materials:

• https://bluejeans.com/s/B6Wbo
• https://docs.google.com/presentation/d/1ouN3eBbRZy10rmBEnGhx9Xrz8vNm5CSSc3nqEIzn0Nw/edit#slide=id.g49a86d12a0_0_130
• https://gist.github.com/garagatyi/edfd4e7fdeba1fdf18d9a0e2404d538d
• https://github.com/eclipse/che-plugin-broker#this-repo-contains-implmentations-of-several-che-plugin-brokers

[ibuziuk]

@rkratky could you please provide structure / template for this part of the documents "architectural insights about plugin brokers". I guess it should probably part of the Extending Eclipse Che section wdyt ? cc: @garagatyi

[1] https://docs.google.com/document/d/1RuLh2w3DPdlYlebadNdf90n_xM5Nw5rHIDEBrXHy6I4/edit#

[rkratky]

could you please provide structure / template for this part

I haven't gotten to it today, but we'll provide you with the modular structure for the planned docs directly in the docs repo, so that you can start filling in. The idea is to split every user story into parts (modules) describing concepts and procedures. Upstream is here: https://github.com/redhat-documentation/modular-docs (but that's just FYI -- we'll set up the skeleton structure).

I guess it should probably part of the Extending Eclipse Che section wdyt ?

Yes, there already is a section about plugin brokers. We'll likely do some reorganizing, but you can work on it in the meantime.

[garagatyi]

@rkratky

Yes, there already is a section about plugin brokers. We'll likely do some reorganizing, but you can work on it in the meantime.

I haven't found any information about plugin brokers in docs. Can you point me to them?

[rkratky]

@garagatyi I meant that it is listed as a topic in the gdoc outline -- I was confirming that the "Extending Che" chapter was going to be the right place for it.

@supriya-bharadwaj is now working on setting it up in the docs repo for you.

[supriya-bharadwaj]

Hello everyone, we have added the templates for the Supporting Che plug-in types with plug-in brokers user story to the repository. You all can begin contributing content, please! :)
Here are a few things to be noted, please:

• An assembly equals a user story. So, the assembly template contains (using the include statement) the modules that will eventually make up this user story.
• The concept-name_to_be_determined.adoc file will contain an overview of the Supporting Che plug-in types with plug-in brokers user story.
• You may want to add more than one concept module by copying this template.
• If needed, you may add a template for reference modules (example: a list of command-line parameters). The name of this template would be reference_name_of-the-reference-module.adoc.
• The procedure-name_to_be_determined_1.adoc file (and the procedure-name_to_be_determined_n.adoc files) will contain the actual procedures for the user to accomplish the task of supporting Che plug-in types with plug-in brokers.
• Every task must be contained in a separate procedure-name_to_be_determined_n.adoc file.
  Note: We may not need all the 5 procedural templates, or we may need more. We can add or delete the empty files as needed.
• In every module, other than the concept module, you can add the prerequisites (if any) and the additional resources (if any).
• We have intentionally named the modules "to be determined" so that you can change them as needed.

Please let us know if any of this is not clear. @rkratky or I would be happy to explain :)
Thanks!

[ibuziuk]

@supriya-bharadwaj @rkratky thank you for setting up the template [1]. However, when talking with @l0rd during prioritization my understanding was, that the docs team will not only provide the template, but also define the basic structure of the content, which OSIO team would use as a skeleton for defying the docs. Currently there is a single user story Supporting Che plug-in types with plug-in brokers without no further content defined. Does it mean that now it is up to the Che OSIO team to define all the further content for this user-story ?

[1] https://github.com/eclipse/che-docs/commit/78e89adda48482fc706fd618028d4c510291b1c4

[rkratky]

@ibuziuk Please, work with @supriya-bharadwaj to define the individual parts of the doc. I'm afraid that without some help, Supriya won't be able to flesh out the required procedures -- we don't have the necessary knowledge/understanding of the topic.

We will always provide as much structure as we can, but, unfortunately, there are topics (such as this one) to which we have had no exposure yet. So, we need your input.

Could you perhaps start by outlining the main areas or actions that need to be described? Based on that, we should be able to suggest a working structure.

[ibuziuk]

@garagatyi will you be able to revise the Supporting Che plug-in types with plug-in brokers user-story and come up with a plan of the working structure, which would be approved by the docs team. Once done, someone else from Che OSIO team would take over and proceed with writing actual docs for each section.

[garagatyi]

@ibuziuk OK

[garagatyi]

@supriya-bharadwaj @rkratky not sure I understand how to do user stories from technical documentation of architecture of the system. But I'll try to explain what we would want to describe in the documentation and hopefully you, as documentation experts, could help to figure out how to transform that into user stories like docs.

[garagatyi]

Below you can find content I suppose we need to write in those docs. @rkratky @supriya-bharadwaj please, review if this suits documentation structure and content standards.

I'm not sure it really follows intentions of being user-story driven, but I tried to do so. Apperently structure shows that such a doc would be too big to fit it on one screen as adviced by docs reccomendations.
If @rkratky and @supriya-bharadwaj could help to identify correct structure and maybe what content is not needed at all it would be way easier for our team to finish docs in a timely manner.

Supporting other plug-in types with Plug-ins Brokers

Che 7 supports plugable plugin types.

Why you might need it:

• Theia supports several types of plugins including VSCode extensions. It could add support of new plugin types in future
• Since Che 7 supports plugable editor implementations we should have an ability to add broker of plugins suitable for a new editor
• It is possible to also implement plugins for other plugins

What plugin broker can do:

• Download binaries and configuration of editors/plugins
• Generate configuration of editors/plugins including sidecars
• Unpack files in it is needed for them to be consumed by an editor
• Send logs of stages of its work to Workspace master to make workspace start more verbose to show why a user waits
• Send error if something goes wrong

How to share binaries between broker and Editor

How to write an implementation of a plugin broker

• Can be written in any language
• What a broker gets on start
• Describe structure of config a broker sends to master
  
  
  
  • No sidecar case
  
  
  • One sidecar case
  
  
  • Multiple sidecars case
  
  
  • How to open a port
    
    
    
    
    
    • public
    
    
    
    • private
    
    
    
  
  
  • How to add commands to workspace
  
  
  • How to add volume (also describe mapping of che volume to a volume from a recipe to a volume from plugin sidecar)
  
  
  • memory limit
  
  
  • container image
  
  
  • environment variables
  
  
  • How to share some info between a plugin and an editor when it is needed for an editor to pick up the plugin (workspace-env field)
  
  
  • What will happen if unsupported field will be send to master
  
  
• What a broker does at end (send error or results to master)
• Processing several plugins at the same time
• Connect to master to send logs and results
• Logs

How to integrate new plugin broker (plugin type support in Che 7)

• Che master configuration
• Add a plugin meta information of a new plugin type to a plugin registry (link to docs how to add a plugin meta info)

[ibuziuk]

Some comments inlined:

Supporting other plug-in types with Plug-ins Brokers

Why other ? the story is called Supporting Che plug-in types with plug-in brokers

How to write an implementation of a plugin broker

This sounds like a different user-story which is out of scope of this issue.

How to integrate new plugin broker (plugin type support in Che 7)

This sounds like a different user-story which is out of scope of this issue.

@garagatyi @rkratky I would probably focus on the following parts of the docs in this issue (originally it was architectural insights about plugin brokers):

• What are plugin brokers in general / what plugin brokers can do / why plugin brokers are needed.
• Description of existing plugin brokers

WDYT ?

[garagatyi]

@ibuziuk I had a completely different idea of what is needed to be documented. Hmm, we probably need input from Robert and maybe @slemeur to avoid not being on the same page.

[ibuziuk]

@garagatyi just to avoid confusion, user-stories How to write an implementation of a plugin broker / How to integrate new plugin broker (plugin type support in Che 7) are super valuable, but I just do not think those are part of this issue. IMO, we should start with smth. basic e.g.

What are plugin brokers in general / what plugin brokers can do / why plugin brokers are needed.
Description of existing plugin brokers

and address other user-stories in separate issues

[garagatyi]

@ibuziuk FYI Che plugin broker repo already contains a description of current implementations https://github.com/eclipse/che-plugin-broker/blob/master/README.md
If we only need what you described than structure would be:

• What are plugin brokers in general (why plugin brokers are needed)
  
  
  
  • Theia supports several types of plugins including VSCode extensions. It could add support of new plugin types in future
  
  
  • Since Che 7 supports plugable editor implementations we should have an ability to add broker of plugins suitable for a new editor
  
  
  • It is possible to also implement plugins for other plugins
  
  
• What plugin brokers can do
  
  
  
  • Download binaries and configuration of editors/plugins
  
  
  • Generate configuration of editors/plugins including sidecars
  
  
  • Unpack files in it is needed for them to be consumed by an editor
  
  
  • Send logs of stages of its work to Workspace master to make workspace start more verbose to show why a user waits
  
  
  • Send error if something goes wrong
  
  
• Description of existing plugin brokers from https://github.com/eclipse/che-plugin-broker/blob/master/README.md

[ibuziuk]

this sounds like a relevant docs to start with. @rkratky @slemeur wdyt ?

[slemeur]

Thanks @garagatyi !

I like the outline proposal. I think it covers exactly what someone needs to understand about the plugin brokers.

Just one suggestion:

• Description of existing plugin brokers from https://github.com/eclipse/che-plugin-broker/blob/master/README.md

You don't need to duplicate the content. Just use a reference like "If you have interested to get more information about the existing plugin brokers packaged with Che, go on the repository here."

(This way, we keep information up-to-date in the readme, and at a single place, no need to duplicate the content)

[slemeur]

Also, could you please add the content in the whole gdoc for Che 7 docs:
https://docs.google.com/document/d/1BH2oUq3gJhsNsKqdUOXpoe1Z9qf9ARTdxXyBNo10l20/edit#bookmark=id.fyeu59qv1p4h

[rkratky]

Apologies for being so late. Thanks for the outline. I like the fact that it begins with the "why".

[garagatyi]

Also, could you please add the content in the whole gdoc for Che 7 docs:
https://docs.google.com/document/d/1BH2oUq3gJhsNsKqdUOXpoe1Z9qf9ARTdxXyBNo10l20/edit#bookmark=id.fyeu59qv1p4h

OSIO-Che team that it would be better to sharethe knowledge about brokers in the team. So, I provided only outline for the content and aprove the content. But content itself should be provided by another team member.

[ibuziuk]

Plugin Broker doc is ready for review - https://github.com/ibuziuk/docs/blob/master/che_plugin_brokers.adoc
Also added to che 7 gdoc -https://docs.google.com/document/d/1BH2oUq3gJhsNsKqdUOXpoe1Z9qf9ARTdxXyBNo10l20/edit#bookmark=id.fyeu59qv1p4h

[supriya-bharadwaj]

Thanks for the content, @ibuziuk . @rkratky or I will look into this soon. :)

[ibuziuk]

@supriya-bharadwaj @garagatyi I'm going to close this issue, so please provide review comments in the gdoc and I will try to swiftly provide relevant updates / fixes in the content.