feat: Provides 'Adding a Visual Studio Code Extension' module #2265

benoitf · 2022-03-30T06:56:44Z

What does this pull request change

Introduce Adding a Visual Studio Code Extension module

What issues does this pull request fix or reference

Specify the version of the product this pull request applies to

master

Pull request checklist

The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.

Any procedure:
- Successfully tested.
Any page or link rename:
- The page contains a redirection for the previous URL.
- Propagate the URL change in:
  - Dashboard default branding data
  - Chectl constants.ts
Builds on Eclipse Che hosted by Red Hat.
the Validate language on files added or modified step reports no vale warnings.

Change-Id: Ide2764fe5bb63fcd5d7592d5c75d67622a7b1cac
Signed-off-by: Florent Benoit fbenoit@redhat.com

reviewer: @deerskindoll

Change-Id: Ide2764fe5bb63fcd5d7592d5c75d67622a7b1cac Signed-off-by: Florent Benoit <fbenoit@redhat.com>

github-actions · 2022-03-30T06:56:57Z

Click here to review and test in web IDE:

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

benoitf · 2022-04-06T12:55:16Z

@deerskindoll it seems that after your changes, the Pull Request is not passing anymore the vale checks

deerskindoll · 2022-04-06T15:11:24Z

requesting peer review

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

rolfedh · 2022-04-06T20:12:17Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+
+{prod-short} has a default plug-in and extensions registry installed in every {prod-short} instance. The Che-Theia IDE searches and installs the plug-ins and extensions from that location.
+
+Check this {prod-short} https://github.com/eclipse-che/che-plugin-registry[registry project] for an overview of default plug-ins, extensions, and source code. An online instance that is refreshed after every commit to the main branch, is located https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/[here]. You can use a different plug-in or extension registry for Che-Theia if you don't work in air gap mode: only the default registry is available there.


In some che-docs topics, link: precedes URLs like this, but not in this PR. Is that okay?

Suggested change

Check this {prod-short} https://github.com/eclipse-che/che-plugin-registry[registry project] for an overview of default plug-ins, extensions, and source code. An online instance that is refreshed after every commit to the main branch, is located https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/[here]. You can use a different plug-in or extension registry for Che-Theia if you don't work in air gap mode: only the default registry is available there.

Check this {prod-short} https://github.com/eclipse-che/che-plugin-registry[registry project] for an overview of [the?] default plug-ins, extensions, and source code. An online instance that refreshes after every commit to the main branch is located https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/[here]. You can use a different plug-in or extension registry for Che-Theia if you don't work in air gap mode: only the default registry is available there.

I'm having trouble making sense of the final sentence.

I don't see an "air gap mode" mentioned in the che-docs. Would it help to say "air-gapped environment", link to a topic, or specify the key parameters for setting up an air-gapped environment, such as airGapContainerRegistryHostname?

@benoitf, does "only the default registry is available there" mean "only the default registry is available in an air-gapped environment?" This seems like the opposite of what I would expect. I expect the user would need to specify a custom (non-default) plug-in or extension registry because they are in an air-gapped environment. The default URLs of the plug-ins and extensions might not be reachable from an air-gapped system.

Using the definite article, "the default plug-ins", makes more sense if the "registry project" topic describes specific plug-ins. Otherwise, if it's an abstract discussion of "plug-ins, extensions, and source code," the current wording is fine.

'air gap' is also named 'restricted environment' sometimes. But you can find definition there https://en.wikipedia.org/wiki/Air_gap_(networking)

And it's used in Che (and docs)

'air gap' is also named 'restricted environment' sometimes. But you can find definition there https://en.wikipedia.org/wiki/Air_gap_(networking)

And it's used in Che (and docs)

Although we should strive to use the terminology consistently, I'm not highlighting "air gap" as a problem. I'm concerned that calling it a "mode" might prompt users to search for an actual software mode when it seems like there might not be one. I'm guessing you mean "an air-gapped or restricted environment" instead.

Otherwise, if there is something like a mode, it's not called a "mode" in the software or documentation and actually consists of one or more parameters that the user must set when operating the software in a restricted environment.

I'll accept any suggested changes but here suggested changes have questions so I never saw this kind of suggested changes.

Does "only the default registry is available there" mean "only the default registry is available in an air-gapped environment?" This seems like the inverse of what I would expect: That the user probably requires use of a custom plug-in or extension registry because they are in an air-gapped environment. The default URLs of the plug-ins and extensions might not be reachable from an air-gapped system.

There is no need to use a custom plug-in or extension registry. Che deploy a registry on the air-gapped environment and in that case it includes all the binaries so there is no need to fetch something externally.

The default URLs of the plug-ins and extensions might not be reachable from an air-gapped system.

everything is reachable in that case (we build and deploy an offline / air-gapped environment registry)

wording fixed

rolfedh · 2022-04-06T20:40:49Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+
+The easiest way to add a Visual Studio Code extension to a workspace is to add it to the `.vscode/extensions.json` file. The main advantage of this method is that it works with all supported {prod-short} IDEs.
+
+If you use the Che-Theia IDE, the extension is installed and configured automatically. If you use a different supported IDE with the Che-Code Visual Studio Code fork, a pop-up with a recommendation to install the extension shows when you start the workspace.


Suggested change

If you use the Che-Theia IDE, the extension is installed and configured automatically. If you use a different supported IDE with the Che-Code Visual Studio Code fork, a pop-up with a recommendation to install the extension shows when you start the workspace.

If you use the Che-Theia IDE, the extension is installed and configured automatically. If you use a different supported IDE with the Che-Code Visual Studio Code fork, the IDE [displays a pop-up with a recommendation/promts you] to install the extension when you start the workspace.

GitHub suggestion implies that we can commit directly the change.
Here it looks that there are two suggestions so it should be two separate GitHub PR suggestions (and people can approve one of them)

wording fixed

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

rolfedh · 2022-04-07T09:19:14Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+  }
+----
+
+*NOTE* 


For comparison, I searched the che-docs repo for admonitions like one this but didn't find any. You can use the asciidoc formatting for admonitions, which looks like this:

NOTE: adlfjakdfj

or

[NOTE] ==== afdasdf ====

The openshift-docs repo standardized on this later format...
I would recommend asking your team which one to use.

This is how asciidoc renders the original format and the two proposed formats:

formatting fixed

rolfedh · 2022-04-07T09:21:53Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+----
+
+*NOTE* 
+If the specified set of extension ids isn't available in the {prod-short} registry, the workspace starts without the extension.


s/id/ID/ throughout.

benoitf · 2022-04-07T09:22:54Z

who should handle the suggested changes from @rolfedh , @deerskindoll or myself ?

rolfedh · 2022-04-07T09:26:24Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+
+[id="che-theia-plug-ins-YAML"]
+== Adding plug-in parameters to `.che/che-theia-plugins.yaml`
+You can add extra parameters to a plug-in by modifying the `.che/che-theia-plugins.yaml` file. These modifications include:


Bulleted lists don't render as such unless they're preceded by a blank line.

formatting fixed

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

deerskindoll · 2022-04-07T09:29:20Z

I'll need your help if that's ok with you. I can handle asciidoc fixes but I can't answer the questions regarding devfile v2, air gap mode etc.

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

rolfedh · 2022-04-07T09:36:26Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+. You have the `.che/che-theia-plugins.yaml` file in the root of the GitHub repository.
+
+.Procedure
+. Add an `override` section in the `.che/che-theia-plugins.yaml` file under the `id` of the plug-in.


wording fixed

rolfedh · 2022-04-07T09:40:04Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+. You have the `.che/che-theia-plugins.yaml` file in the root of the GitHub repository.
+
+.Procedure
+. Add an `override` section in the `.che/che-theia-plugins.yaml` file under the `id` of the extension. 


"add...to" here and elsewhere

wording fixed

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

rolfedh · 2022-04-07T09:45:43Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+[id="visual-studio-code-extensions-in-devfile"]
+== Defining Visual Studio Code extension attributes in the devfile
+
+In case it's not possible to add extra files in the GitHub repository, you can define some of the plug-in or extension attributes by inlining them in the devfile. You can use this procedure with both `.vscode/extensions.json` and `.che/che-theia-plugins.yaml` file contents.


For minimalism:

In case > If ?

it's not possible to > you can't ?

Is there a more commonly understood equivalent for "inlining" that preserves the meaning?

wording fixed

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

rolfedh · 2022-04-07T09:51:33Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+.Procedure
+. Add the extension ID to the `.vscode/extensions.json` file. Use a `.` sign to separate the publisher and extension names:
+
+*EXAMPLE*


Didn't find any other instances of *EXAMPLE* in che-docs. Consider adopting the standard code block titles throughout, like this:

.Example <optional descriptive text>

formatting fixed

rolfedh · 2022-04-07T10:04:52Z

modules/end-user-guide/pages/adding-a-vscode-extension.adoc

+In case it's not possible to add extra files in the GitHub repository, you can define some of the plug-in or extension attributes by inlining them in the devfile. You can use this procedure with both `.vscode/extensions.json` and `.che/che-theia-plugins.yaml` file contents.
+
+=== Inlining `.vscode/extensions.json` file
+Use `.vscode/extensions.json` file contents to inline extension attributes in the devfile.


Part of the issue with using the adjective, "inline," as a verb is that when you use it next to a noun, as shown here, the reader might experience some semantic noise:
raising the question, "Is a verb missing between "to" and "inline extension attributes?"
Perhaps subsitute it with "add" or "insert?" WDYT?

reworded as "inlining the extension/plug-in attributes"

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

rolfedh · 2022-04-07T14:54:21Z

who should handle the suggested changes from @rolfedh , @deerskindoll or myself ?

My role here is to serve as peer reviewer. I believe @deerskindoll, as the technical writer, should make the updates for language-related issues. I'll at-mention you, @benoitf, for any questions about the software functionality.

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

deerskindoll

approved

benoitf · 2022-04-07T16:54:45Z

Merging as all checks are green and it has been approved by Jana and Ilya

feat: Provides 'Adding a Visual Studio Code Extension' module

17b9e1b

Change-Id: Ide2764fe5bb63fcd5d7592d5c75d67622a7b1cac Signed-off-by: Florent Benoit <fbenoit@redhat.com>

benoitf requested review from rkratky and themr0c as code owners March 30, 2022 06:56

benoitf mentioned this pull request Mar 30, 2022

feat: Provides 'Adding a Visual Studio Code Extension' module #2249

Closed

6 tasks

che-bot added the status/code-review label Mar 30, 2022

benoitf mentioned this pull request Mar 31, 2022

User guide: update content for devworkspace, in the master branch eclipse-che/che#21285

Closed

13 tasks

themr0c added this to the 7.44 milestone Apr 1, 2022

ibuziuk approved these changes Apr 6, 2022

View reviewed changes

ibuziuk reviewed Apr 6, 2022

View reviewed changes

modules/end-user-guide/pages/adding-a-vscode-extension.adoc Outdated Show resolved Hide resolved

CHE-21296 edits (#7)

0791149

fixing monospace issues

fccfa05

rolfedh reviewed Apr 6, 2022

View reviewed changes

modules/end-user-guide/pages/adding-a-vscode-extension.adoc Outdated Show resolved Hide resolved

rolfedh reviewed Apr 6, 2022

View reviewed changes

modules/end-user-guide/pages/adding-a-vscode-extension.adoc Outdated Show resolved Hide resolved

rolfedh reviewed Apr 6, 2022

View reviewed changes

modules/end-user-guide/pages/adding-a-vscode-extension.adoc Outdated Show resolved Hide resolved

rolfedh reviewed Apr 7, 2022

View reviewed changes

modules/end-user-guide/pages/adding-a-vscode-extension.adoc Outdated Show resolved Hide resolved

rolfedh reviewed Apr 7, 2022

View reviewed changes

modules/end-user-guide/pages/adding-a-vscode-extension.adoc Outdated Show resolved Hide resolved

rolfedh reviewed Apr 7, 2022

View reviewed changes

modules/end-user-guide/pages/adding-a-vscode-extension.adoc Outdated Show resolved Hide resolved

rolfedh reviewed Apr 7, 2022

View reviewed changes

modules/end-user-guide/pages/adding-a-vscode-extension.adoc Outdated Show resolved Hide resolved

deerskindoll and others added 2 commits April 7, 2022 11:45

Update modules/end-user-guide/pages/adding-a-vscode-extension.adoc

8df50e1

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

Update modules/end-user-guide/pages/adding-a-vscode-extension.adoc

78cd110

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

rolfedh reviewed Apr 7, 2022

View reviewed changes

deerskindoll and others added 2 commits April 7, 2022 11:46

Update modules/end-user-guide/pages/adding-a-vscode-extension.adoc

5cdb312

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

Update modules/end-user-guide/pages/adding-a-vscode-extension.adoc

222c80a

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

rolfedh reviewed Apr 7, 2022

View reviewed changes

deerskindoll and others added 2 commits April 7, 2022 13:52

Update modules/end-user-guide/pages/adding-a-vscode-extension.adoc

7aa844d

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

Update modules/end-user-guide/pages/adding-a-vscode-extension.adoc

39a6597

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

deerskindoll and others added 2 commits April 7, 2022 17:22

Update modules/end-user-guide/pages/adding-a-vscode-extension.adoc

cca238d

Co-authored-by: Rolfe Dlugy-Hegwer <rolfedh@users.noreply.github.com>

peer review suggestions incorporated

4a9934f

deerskindoll approved these changes Apr 7, 2022

View reviewed changes

typos fixed

b1eaf41

benoitf merged commit f8447a0 into eclipse-che:master Apr 7, 2022

che-bot removed the status/code-review label Apr 7, 2022


		{prod-short} has a default plug-in and extensions registry installed in every {prod-short} instance. The Che-Theia IDE searches and installs the plug-ins and extensions from that location.

		Check this {prod-short} https://github.com/eclipse-che/che-plugin-registry[registry project] for an overview of default plug-ins, extensions, and source code. An online instance that is refreshed after every commit to the main branch, is located https://eclipse-che.github.io/che-plugin-registry/main/v3/plugins/[here]. You can use a different plug-in or extension registry for Che-Theia if you don't work in air gap mode: only the default registry is available there.


		The easiest way to add a Visual Studio Code extension to a workspace is to add it to the `.vscode/extensions.json` file. The main advantage of this method is that it works with all supported {prod-short} IDEs.

		If you use the Che-Theia IDE, the extension is installed and configured automatically. If you use a different supported IDE with the Che-Code Visual Studio Code fork, a pop-up with a recommendation to install the extension shows when you start the workspace.

+                }
+              ----
+              *NOTE*

feat: Provides 'Adding a Visual Studio Code Extension' module #2265

feat: Provides 'Adding a Visual Studio Code Extension' module #2265

Conversation

benoitf commented Mar 30, 2022 • edited Loading

What does this pull request change

What issues does this pull request fix or reference

Specify the version of the product this pull request applies to

Pull request checklist

github-actions bot commented Mar 30, 2022

benoitf commented Apr 6, 2022

deerskindoll commented Apr 6, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolfedh Apr 6, 2022 • edited Loading

Choose a reason for hiding this comment

rolfedh Apr 6, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolfedh Apr 7, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolfedh Apr 7, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benoitf commented Apr 7, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deerskindoll commented Apr 7, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolfedh Apr 7, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolfedh Apr 7, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolfedh commented Apr 7, 2022

deerskindoll left a comment

Choose a reason for hiding this comment

benoitf commented Apr 7, 2022

benoitf commented Mar 30, 2022 •

edited

Loading

rolfedh Apr 6, 2022 •

edited

Loading

rolfedh Apr 6, 2022 •

edited

Loading

rolfedh Apr 7, 2022 •

edited

Loading

rolfedh Apr 7, 2022 •

edited

Loading

rolfedh Apr 7, 2022 •

edited

Loading

rolfedh Apr 7, 2022 •

edited

Loading