Merge pull request #754 from MichalMaler/i1153-VS_Code_extension_in_t…

…he_Che

Che 7: Using a Visual Studio Code extension in Che

src/main/pages/che-7/hands-on-guidance/assembly_adding-che-plug-in-registry-vs-code-extension-to-a-workspace.adoc

@@ -0,0 +1,14 @@
+:parent-context-of-adding-che-plug-in-registry-vs-code-extension-to-a-workspace: {context}
+
+[id='adding-che-plug-in-registry-vs-code-extension-to-a-workspace_{context}']
+= Adding plug-in registry VS Code extension to a workspace
+
+:context: adding-che-plug-in-registry-vs-code-extension-to-a-workspace
+
+When the required VS Code extension is added into a Che plug-in registry, the user can add it into the workspace through the *Che Plugins* panel or through the workspace configuration.
+
+include::proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc[leveloffset=+1]
+
+include::proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc[leveloffset=+1]
+
+:context: {parent-context-of-adding-che-plug-in-registry-vs-code-extension-to-a-workspace}

src/main/pages/che-7/hands-on-guidance/assembly_contributor-tasks.adoc

@@ -1,11 +1,11 @@
 ---
 title: Contributor tasks
-keywords: 
+keywords:
 tags: []
 sidebar: che_7_docs
 permalink: che-7/contributor-tasks.html
 folder: che-7/hands-on-guidance
-summary: 
+summary:
 ---
 
 :parent-context-of-contributor-tasks: {context}
@@ -20,12 +20,13 @@ summary:
 
 // [discrete]
 // == Prerequisites
-// 
+//
 // * A bulleted list of conditions that must be satisfied before the user starts following this assembly.
 // * You can also link to other modules or assemblies the user must follow before starting this assembly.
 // * Delete the section title and bullets if the assembly has no prerequisites.
 
 
+include::assembly_using-a-visual-studio-code-extension-in-che.adoc[leveloffset=+1]
 
 // include::proc_developing-your-first-plug-in.adoc[leveloffset=+1]
 
@@ -45,7 +46,7 @@ include::proc_adding-support-for-a-new-debugger.adoc[leveloffset=+1]
 
 // [discrete]
 // == Additional resources
-// 
+//
 // * A bulleted list of links to other material closely related to the contents of the concept module.
 // * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 // * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].

src/main/pages/che-7/hands-on-guidance/assembly_end-user-tasks.adoc

@@ -15,16 +15,14 @@ summary:
 
 :context: end-user-tasks
 
-
-This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. Can include more than one paragraph. Consider using the information from the user story.
-
-[id='prerequisites-{context}']
-== Prerequisites
-
-* A bulleted list of conditions that must be satisfied before the user starts following this assembly.
-* You can also link to other modules or assemblies the user must follow before starting this assembly.
-* Delete the section title and bullets if the assembly has no prerequisites.
-
+// This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. Can include more than one paragraph. Consider using the information from the user story.
+// 
+// [id='prerequisites-{context}']
+// == Prerequisites
+// 
+// * A bulleted list of conditions that must be satisfied before the user starts following this assembly.
+// * You can also link to other modules or assemblies the user must follow before starting this assembly.
+// * Delete the section title and bullets if the assembly has no prerequisites.
 
 include::proc_creating-a-workspace-from-code-sample.adoc[leveloffset=+1]
 
@@ -34,21 +32,20 @@ include::proc_configuring-a-che-workspace-using-a-devfile.adoc[leveloffset=+1]
 
 // include::proc_importing-a-kubernetes-application-into-a-che-worskspace.adoc[leveloffset=+1]
 
-// include::proc_using-a-visual-studio-code-extension-in-che.adoc[leveloffset=+1]
+include::assembly_using-a-visual-studio-code-extension-in-che.adoc[leveloffset=+1]
 
 // include::proc_configuring-plug-ins.adoc[leveloffset=+1]
-
+// 
 // include::proc_remotely-accessing-your-workspace.adoc[leveloffset=+1]
-
+// 
 // include::proc_configuring-your-vcs-credentials-for-your-workspaces.adoc[leveloffset=+1]
 
 
-
-[id='related-information-{context}']
-== Related information
-
-* A bulleted list of links to other material closely related to the contents of the concept module.
-* For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
-* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+// [id='related-information-{context}']
+// == Related information
+// 
+// * A bulleted list of links to other material closely related to the contents of the concept module.
+// * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+// * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 
 :context: {parent-context-of-end-user-tasks}

src/main/pages/che-7/hands-on-guidance/assembly_publishing-a-vs-code-extension-into-the-che-plug-in-registry.adoc

@@ -0,0 +1,13 @@
+:parent-context-of-publishing-a-vs-code-extension-into-the-che-plug-in-registry: {context}
+
+[id='publishing-a-vs-code-extension-into-the-che-plug-in-registry_{context}']
+= Publishing a VS Code extension into the Che plug-in registry
+
+:context: publishing-a-vs-code-extension-into-the-che-plug-in-registry
+
+// PUT SOME INTRO HERE
+To set up a custom plug-in registry, see the link:TODO[Registries customization] article.
+
+include::proc_writing-a-meta-yaml-file-and-adding-it-to-a-plug-in-registry.adoc[leveloffset=+1]
+
+:context: {parent-context-of-publishing-a-vs-code-extension-into-the-che-plug-in-registry}

src/main/pages/che-7/hands-on-guidance/assembly_using-a-visual-studio-code-extension-in-che.adoc

@@ -0,0 +1,29 @@
+:parent-context-of-using-a-visual-studio-code-extension-in-che: {context}
+
+[id='using-a-visual-studio-code-extension-in-che_{context}']
+= Using a Visual Studio Code extension in Che
+
+:context: using-a-visual-studio-code-extension-in-che
+
+Starting with Eclipse Che 7, Visual Studio Code (VS Code) extensions can be installed to extend the functionality of a Che workspace. VS Code extensions can run in the Che-Theia editor container, or they can be packaged in their own isolated and pre-configured containers with their prerequisites.
+
+This document describes:
+
+* Use of a VS Code extension in Che with workspaces
+* Che Plug-ins panel
+* How to publish a VS Code extension in the Che plug-in registry (to share the extension with other Che users)
++
+** The extension-hosting sidecar container and the use of the extension in a devfile are optional for this.
+** How to review the compatibility of the VS Code extensions to be informed whether a specific API is supported or has not been implemented yet.
+
+include::proc_importing-a-vs-code-extension-in-the-che-theia-editor.adoc[leveloffset=+1]
+
+include::assembly_publishing-a-vs-code-extension-into-the-che-plug-in-registry.adoc[leveloffset=+1]
+
+include::assembly_adding-che-plug-in-registry-vs-code-extension-to-a-workspace.adoc[leveloffset=+1]
+
+include::proc_choosing-the-sidecar-image.adoc[leveloffset=+1]
+
+include::proc_verifying-the-vs-code-extension-api-compatibility-level.adoc[leveloffset=+1]
+
+:context: {parent-context-of-using-a-visual-studio-code-extension-in-che}

src/main/pages/che-7/hands-on-guidance/proc_adding-the-vs-code-extension-using-the-che-plugins-panel.adoc

@@ -0,0 +1,17 @@
+[id="adding-the-vs-code-extension-using-the-che-plugins-panel_{context}"]
+= Adding the VS Code extension using the Che Plugins panel
+
+.Procedure
+
+To add the VS Code extension using the *Che Plugin* panel:
+
+. Open the *Che Plugin* panel.
+
+. Change the current registry to the registry in which the VS Code extension was added.
+
+. In the search bar, click the *Menu* button and then click *Change Registry* to choose the registry from the list. If the required registry is not in the list, add it using the *Add Registry* menu option. The registry link should point to the `plugins` segment of the registry. For example: `https://my-registry.com/v3/plugins/index.json`.
++
+image::extensibility/vs-code-extension-change-registry.jpg[link="{imagesdir}/extensibility/vs-code-extension-change-registry.jpg"]
+
+. Search for the required plug-in using the filter, and then click the btn:[Install] button.
+. Restart the workspace for the changes to take effect.

src/main/pages/che-7/hands-on-guidance/proc_adding-the-vs-code-extension-using-the-workspace-configuration.adoc

@@ -0,0 +1,23 @@
+[id="adding-the-vs-code-extension-using-the-workspace-configuration_{context}"]
+= Adding the VS Code extension using the workspace configuration
+
+.Procedure
+
+To add the VS Code extension using the workspace configuration:
+
+. Click the *Workspaces* tab on the *Dashboard* and select the workspace in which you want to add the plug-in. The *Workspace __<workspace-name>__* window opens showing the details of the workspace.
+
+. Click the *devfile* tab.
+
+. Locate the *components* section, and add a new entry with the following structure:
++
+[source,yaml,subs="+quotes"]
+----
+ - type: chePlugin
+   id:              <1>
+----
+<1> Link to the `meta.yaml` file in your registry, for example, `https://my-plugin-registry/v3/plugins/__<publisher>__/__<plug-inName>__/__<plug-inVersion>__/meta.yaml`
++
+Che automatically adds the other fields to the new component.
+
+. Restart the workspace for the changes to take effect.

src/main/pages/che-7/hands-on-guidance/proc_choosing-the-sidecar-image.adoc

@@ -0,0 +1,30 @@
+[id="choosing-the-sidecar-image_{context}"]
+= Choosing the sidecar image
+
+Che plug-ins are special services that extend the Che workspace capabilities. Che plug-ins are packaged as containers. The containers that the plug-ins are packaged into run as _sidecars_ of the Che workspace editor and augment its capabilities.
+
+.Procedure
+
+To choose a sidecar image:
+
+. If the VS code extension does not have any external dependencies, use `eclipse/che-theia-endpoint-runtime: next` as a sidecar container image for the extension.
++
+[NOTE]
+====
+In addition to the `eclipse/che-theia-endpoint-runtime:next` base image, the following ready-to-use sidecar images that include language-specific dependencies are available:
+
+* eclipse/che-remote-plugin-runner-java8
+* eclipse/che-remote-plugin-runner-java11
+* eclipse/che-remote-plugin-go-1.10.7
+* eclipse/che-remote-plugin-python-3.7.3
+* eclipse/che-remote-plugin-dotnet-2.2.105
+* eclipse/che-remote-plugin-php7
+* eclipse/che-remote-plugin-kubernetes-tooling-1.0.0
+* eclipse/che-remote-plugin-kubernetes-tooling-0.1.17
+* eclipse/che-remote-plugin-openshift-connector-0.0.17
+* eclipse/che-remote-plugin-openshift-connector-0.0.21
+====
+
+. If a VS Code extension has external dependencies that are not found in one of the ready-to-use images, use a container image that contains the needed dependencies for the extension and is based on the `eclipse/che-theia-endpoint-runtime:next` image.
++
+Example: the `FROM` directive should be similar to `FROM eclipse/che-theia-endpoint-runtime:next`. This is required because this base image contains tools for running the remote VS Code extension and communications between the sidecar and the Che-Theia editor, so that the VS Code extension does not have to know that it is a remote one.

src/main/pages/che-7/hands-on-guidance/proc_using-a-visual-studio-code-extension-in-che.adoc → src/main/pages/che-7/hands-on-guidance/proc_devfile-and-plugin-registries-customization.adoc

@@ -1,5 +1,27 @@
-[id="using-a-visual-studio-code-extension-in-che_{context}"]
-= Using a Visual Studio Code extension in Che
+// Module included in the following assemblies:
+//
+// <List assemblies here, each on a new line>
+
+// This module can be included from assemblies using the following include statement:
+// include::<path>/proc_devfile-and-plugin-registries-customization.adoc[leveloffset=+1]
+
+// The file name and the ID are based on the module title. For example:
+// * file name: proc_doing-procedure-a.adoc
+// * ID: [id='proc_doing-procedure-a_{context}']
+// * Title: = Doing procedure A
+//
+// The ID is used as an anchor for linking to the module. Avoid changing
+// it after the module has been published to ensure existing links are not
+// broken.
+//
+// The `context` attribute enables module reuse. Every module's ID includes
+// {context}, which ensures that the module has a unique ID even if it is
+// reused multiple times in a guide.
+//
+// Start the title with a verb, such as Creating or Create. See also
+// _Wording of headings_ in _The IBM Style Guide_.
+[id="devfile-and-plugin-registries-customization_{context}"]
+= Devfile and Plugin registries customization
 
 This paragraph is the procedure module introduction: a short description of the procedure.
 
@@ -25,3 +47,4 @@ This paragraph is the procedure module introduction: a short description of the
 * A bulleted list of links to other material closely related to the contents of the procedure module.
 * For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+

src/main/pages/che-7/hands-on-guidance/proc_importing-a-vs-code-extension-in-the-che-theia-editor.adoc

@@ -0,0 +1,34 @@
+[id="proc_importing-a-visual-studio-code-extension-in-the-che-theia-editor-adoc_{context}"]
+= Importing a VS Code extension in the Che-Theia editor
+
+This section describes how to install a Visual Studio Code (VS Code) extension from the link:https://marketplace.visualstudio.com/vscode[VS Code marketplace] in a Che workspace when using Che-Theia as the Che editor component.
+
+This method of installing VS Code extensions is for extensions that do not have runtime dependencies. To install extensions that require particular dependencies (tools, environment variables, runtime servers), see section xref:publishing-a-vs-code-extension-into-the-che-plug-in-registry_using-a-visual-studio-code-extension-in-che[].
+
+.Prerequisites
+
+* Configure the Che-Theia memory limit with 512 MB RAM or more to run the Che-Theia editor. In addition, reserve sufficient memory for the VS code extensions. The specific amount of memory required depends on the extensions used.
+
+.Procedure
+
+To import a VS Code extension in the Che Theia editor:
+
+. Navigate to the link:https://marketplace.visualstudio.com/vscode[VS Code marketplace], locate the required extension, and copy the *VS Code Quick Open* code to the clipboard.
+
+. Open the *Che Plugins* panel in the Che-Theia IDE. If the panel is not shown, use the *View -> Che Plugins* menu options from the main menu.
+
+. For macOS users, paste the install command, or the install button into the *Che Plugins* panel.
++
+image::extensibility/vs-code-extension-installation.jpg[link="{imagesdir}/extensibility/vs-code-extension-installation.jpg"]
+
+. In the *Install extension* dialog box, click *Install* to start the installation. The *VS Code plugin has been installed* message indicates successful installation of the plug-in.
+
+. In the top-left corner of the window, click *Click here to apply changes and restart your workspace* to restart the workspace and apply the changes.
++
+image::extensibility/vs-code-extension-apply-restart.jpg[link="{imagesdir}/extensibility/vs-code-extension-apply-restart.jpg"]
+
+. In the *Restart Workspace* dialog box, click *Restart* to confirm the action.
++
+image::extensibility/vs-code-extension-restart-workspace.jpg[link="{imagesdir}/extensibility/vs-code-extension-restart-workspace.jpg"]
+
+After the workspace restarts, the added VS Code extensions launch.

src/main/pages/che-7/hands-on-guidance/proc_verifying-the-vs-code-extension-api-compatibility-level.adoc

@@ -0,0 +1,20 @@
+[id="verifying-the-vs-code-extension-api-compatibility-level_{context}"]
+= Verifying the VS Code extension API compatibility level
+
+Che-Theia does not fully support the VS Code extensions API. The link:https://github.com/che-incubator/vscode-theia-comparator/[vscode-theia-comparator] is used to analyze the compatibility between the Che-Theia plug-in API and the VS Code extension API. This tool runs in a nightly cycle, and the results are published at the link:https://github.com/che-incubator/vscode-theia-comparator/[vscode-theia-comparator] GitHub page.
+
+.Prerequisites
+
+* Personal GitHub access token. For information on creating a personal access token for the command line see the link:https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line[Creating a personal access token for the command line]. A GitHub access token is required to increase the GitHub download limit for your IP address.
+
+.Procedure
+
+To run the *vscode-theia comparator* manually:
+
+. Clone the link:https://github.com/che-incubator/vscode-theia-comparator/[vscode-theia-comparator] repository, and build it using the `yarn` command.
+
+. Set the `GITHUB_TOKEN` environment variable to your token.
+
+. Execute the `yarn run generate` command to generate a report.
+
+. Open the `out/status.html` file to view the report.