From a80c00bd3233bc36f9acf2e69f9bd9937edd86d2 Mon Sep 17 00:00:00 2001
From: JohnHake <john.hake@jetbrains.com>
Date: Sat, 15 Jun 2019 20:29:24 -0700
Subject: [PATCH] Add comments from review.

---
 .idea/gradle.xml                              |   4 +-
 .idea/misc.xml                                |   2 +-
 code_samples/action_basics/.gitignore         |  11 +
 .../src/main/resources/META-INF/plugin.xml    |   2 +-
 code_samples/gradle_plugin_demo/build.gradle  |   4 +
 intro/sdk_code_guidelines.md                  | 164 +++++++++++
 tutorials/build_system.md                     |  16 +-
 tutorials/build_system/deployment.md          |   2 +
 tutorials/build_system/gradle_guide.md        |  34 +--
 tutorials/build_system/prerequisites.md       | 257 ++++++++++++------
 10 files changed, 383 insertions(+), 113 deletions(-)
 create mode 100644 code_samples/action_basics/.gitignore
 create mode 100644 intro/sdk_code_guidelines.md

diff --git a/.idea/gradle.xml b/.idea/gradle.xml
index e6bab328d..7d1133953 100644
--- a/.idea/gradle.xml
+++ b/.idea/gradle.xml
@@ -3,17 +3,15 @@
   <component name="GradleSettings">
     <option name="linkedExternalProjectsSettings">
       <GradleProjectSettings>
-        <option name="disableWrapperSourceDistributionNotification" value="true" />
         <option name="distributionType" value="DEFAULT_WRAPPED" />
         <option name="externalProjectPath" value="$PROJECT_DIR$/code_samples/action_basics" />
         <option name="gradleHome" value="C:/Program Files (x86)/Gradle/gradle-2.9" />
-        <option name="gradleJvm" value="1.8" />
+        <option name="gradleJvm" value="1.8 202b1483.58" />
         <option name="modules">
           <set>
             <option value="$PROJECT_DIR$/code_samples/action_basics" />
           </set>
         </option>
-        <option name="useQualifiedModuleNames" value="true" />
       </GradleProjectSettings>
       <GradleProjectSettings>
         <option name="distributionType" value="DEFAULT_WRAPPED" />
diff --git a/.idea/misc.xml b/.idea/misc.xml
index 401cae41b..a8f1d4d00 100644
--- a/.idea/misc.xml
+++ b/.idea/misc.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="ExternalStorageConfigurationManager" enabled="true" />
-  <component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" default="false" project-jdk-name="IC-191.6183.87" project-jdk-type="IDEA JDK">
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" default="false" project-jdk-name="IU-191.7479.19" project-jdk-type="IDEA JDK">
     <output url="file://$PROJECT_DIR$/Build" />
   </component>
 </project>
\ No newline at end of file
diff --git a/code_samples/action_basics/.gitignore b/code_samples/action_basics/.gitignore
new file mode 100644
index 000000000..8388aebc6
--- /dev/null
+++ b/code_samples/action_basics/.gitignore
@@ -0,0 +1,11 @@
+# Created by .ignore support plugin (hsz.mobi)
+### Gradle template
+.gradle
+build/
+
+# Ignore Gradle GUI config
+gradle-app.setting
+
+# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
+!gradle-wrapper.jar
+
diff --git a/code_samples/action_basics/src/main/resources/META-INF/plugin.xml b/code_samples/action_basics/src/main/resources/META-INF/plugin.xml
index 684a22395..6aea96a73 100644
--- a/code_samples/action_basics/src/main/resources/META-INF/plugin.xml
+++ b/code_samples/action_basics/src/main/resources/META-INF/plugin.xml
@@ -5,7 +5,7 @@
   <id>org.intellij.sdk.action</id>
 
   <!-- Text to display as name on Preferences/Settings | Plugin page -->
-  <name>SDK Action Sample Project</name>
+  <name>SDK: Action Sample Project</name>
 
   <!-- The version of this plugin -->
   <version>2.0.0</version>
diff --git a/code_samples/gradle_plugin_demo/build.gradle b/code_samples/gradle_plugin_demo/build.gradle
index e4a666d54..05433faea 100644
--- a/code_samples/gradle_plugin_demo/build.gradle
+++ b/code_samples/gradle_plugin_demo/build.gradle
@@ -1,3 +1,7 @@
 plugins {
   id "org.jetbrains.intellij" version "0.4.7"
 }
+
+
+sourceCompatibility = 1.8
+
diff --git a/intro/sdk_code_guidelines.md b/intro/sdk_code_guidelines.md
new file mode 100644
index 000000000..3f8d8aee2
--- /dev/null
+++ b/intro/sdk_code_guidelines.md
@@ -0,0 +1,164 @@
+---
+title: Guidelines for Creating IntelliJ Platform SDK Code Samples
+---
+
+This document describes the coding guidelines used for authoring open source IntelliJ Platform SDK code samples.
+Before you begin, please read this page thoroughly as well as the [Code of Conduct](/CODE_OF_CONDUCT.md) and [License](https://github.com/JetBrains/intellij-sdk-docs/blob/master/LICENSE.txt) documents.
+For information about contributing to the IntelliJ Platform itself visit [Contributing to the IntelliJ Platform](/basics/platform_contributions.md).
+
+  * Dummy list item
+  {:toc}
+  
+## Objectives
+Keep the following considerations in mind while authoring an SDK code sample:
+* The purpose of an SDK sample is to demonstrate an implementation pattern to build on top of subsystems and components of the IntelliJ Platform.
+* SDK code samples are instructional code, intended to teach.
+  * Instructional code differs from production code in some key aspects:
+    * Sacrifice some robustness in the interest of simplicity and brevity.
+      Use error checking where it is necessary to make a point about an implementation pitfall.
+    * Keep implementations as simple as possible, but use the full features of the IntelliJ Platform, Java language, and libraries. 
+    * Use meaningful names for interfaces, classes, fields, methods, and extension points.
+    * Write instructional JavaDoc comments.    
+  * Code samples replace lots of documentation. 
+* Aim for two levels of SDK samples:
+  * A _basic_ sample is focused on a particular subject by demonstrating a limited area of the IntelliJ Platform. 
+    It should show all the components and architecture but ultimately accomplish something elementary. 
+    For example, demonstrate persistence by storing only a `String`.
+  * An _advanced_ sample demonstrates how different parts of the IntelliJ Platform integrate and work together. 
+    For example, combining inspections or intentions with non-trivial PsiTree manipulation.
+ 
+Ultimately, the goal is to provide developers with roadmaps for implementing functionality in an IntelliJ Platform-based plugin.
+Each roadmap should contain:
+* Pointers to SDK documentation about the IntelliJ Platform APIs needed to implement the functionality.
+* Pointers to relevant _basic_ SDK sample plugins.
+* Pointers to related _advanced_ SDK sample plugins.
+
+## Naming Conventions for SDK Plugins
+For _basic_ samples, the naming convention is focused on the IntelliJ Platform APIs being demonstrated.
+For example, `foo_basics` where `foo` corresponds to an IntelliJ Platform feature, framework, or component.
+Some naming examples include `facet_basics` and `editor_basics`.
+There is only one _basic_ sample per IntelliJ Platform API area.
+
+For _advanced_ code samples, the name should reflect the complex functionality delivered by the plugin rather than the IntelliJ Platform APIs.
+Advanced samples will be cross-referenced to the IntelliJ Platform APIs demonstrated in the sample.
+
+Note that the naming convention relates to the `Artifact ID`, which is the Gradle property `rootProject.name`.
+This is different than the `<name>` definition provided in the [`plugin.xml`](#pluginxml-conventions) file.
+See the [Plugin Gradle Properties](/tutorials/build_system/prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for more information about the distinction.
+
+
+## Plugin Copyright Statements
+Use the standard intellij-community copyright notice in all sample plugins authored by JetBrains:
+```text  
+Copyright 2000-$today.year JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file."  
+```
+The copyright statement must appear in every source file with the `$today.year` [Velocity](https://www.jetbrains.com/help/idea/copyright-profiles.html) template resolved.
+
+## Plugin ID Conventions
+The `Group ID` for SDK plugins is always `org.intellij.sdk`.
+In general, the plugin ID is the `Group ID` concatenated with the `Artifact ID`.
+
+For _basic_ code samples, it is not necessary to include "basic" in the plugin ID.
+A plugin like `facet_basics` has the plugin ID `org.intellij.sdk.facet`.
+
+## Plugin Package Names
+Packages in plugins should begin with the plugin ID.
+If there is only one package in a plugin, then the package name is the same as the plugin ID.
+
+## Plugin Directory Structure
+SDK sample code should have a standard directory footprint.
+Standardized structure not only makes the samples simpler to navigate and understand, but it builds on the default Gradle plugin project structure.
+The following is the directory structure for a `foo_basics` plugin.
+```text
+code_samples/
+  foo_basics/
+    gradle/
+    src/
+      main/
+        java/
+          icons/
+            FooBasicsIcons.java
+        resources/
+          icons/
+            sdk.svg           # The standard SDK icon for menus, etc.
+          META-INF/
+            plugin.xml        # The plugin configuration file
+            pluginIcon.svg    # The standard SDK plugin icon
+      test/                   # Omit if there are no tests
+        java/
+        resources/
+    build.gradle
+    gradlew
+    gradle.bat
+    settings.gradle
+```
+
+## build.gradle Conventions 
+New SDK code samples should be developed [using Gradle](/tutorials/build_system.md). 
+As of this writing, the use of Gradle in SDK code samples still relies heavily on the `plugin.xml` for specifying the plugin configuration.
+At a later, second phase, the SDK code samples will transition to rely more on the Gradle configuration. 
+
+The default contents of a `build.gradle` file are produced by the [New Project Wizard](/tutorials/build_system/prerequisites.md#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard). 
+A consistent structure for an SDK code sample's `build.gradle` file is important for clarity and is based on the default produced by the project wizard. 
+Comments in SDK code sample `build.gradle` files should only draw attention to the parts of the Gradle configuration that are unique for a plugin.
+
+For SDK code samples, a few alterations are needed to the default build.gradle file produced by the plugin wizard:
+* Maintain the Gradle properties `version` (`project.version`) and `group` (`project.group`).
+  See the [Plugin Gradle Properties](/tutorials/build_system/prerequisites.md#plugin-gradle-properties-and-plugin-configuration-file-elements) section for how these Gradle properties relate to the elements in `plugin.xml`.
+* Add the following statements to the [Setup DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#setup-dsl) (`intellij{}`) section:
+  ```groovy
+      // Prevents patching <idea-version> attributes in plugin.xml
+      updateSinceUntilBuild = false 
+      // Define a shared sandbox directory for running code sample plugins within an IDE.
+      sandboxDirectory = file("${project.projectDir}/../_idea-sandbox")
+  ``` 
+* Remove the [Patching DSL](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#patching-dsl) (`patchPluginXml{}`) section.
+  It is not needed in SDK samples.
+* Add the `javadoc` task to build documentation for the code sample:
+  ```groovy
+    // Force javadoc rebuild before jar is built
+    jar.dependsOn javadoc
+  ```
+
+## plugin.xml Conventions
+A consistent structure for the [`plugin.xml`](/basics/plugin_structure/plugin_configuration_file.md) configuration file of an SDK code sample is important because we want to draw attention to the unique parts of the file for a plugin.
+Inconsistent element order is visually noisy.
+Comment profusely about unique elements and configurations, and comment sparingly for the rest.
+
+The sequence of elements in an SDK code sample `plugin.xml` file is:
+* `<id>` Use the fully qualified [Plugin ID](#plugin-id-conventions).
+* `<name>` The name value does not have to match the [Plugin Name](#naming-conventions-for-sdk-plugins).
+  It might reflect the functionality of the plugin.
+  The name must start with "SDK: ".
+* `<version>` The code sample's version in MAJOR.MINOR.FIX format.
+  * MAJOR corresponds to a significant upgrade in functionality.
+  * MINOR corresponds to minor refactoring and small improvements in functionality. 
+  * FIX corresponds to changes that fix problems without significant refactoring.
+* `<idea-version/>` Set the attributes:
+  * `since-build` attribute to the earliest compatible build number of the IntelliJ Platform.
+    The default for SDK samples is "173".
+  * `until-build` Omit this attribute for new sample plugins.
+    SDK code samples are reviewed before every major release (20XX.1) to ensure compatibility with the latest IntelliJ Platform.
+    Add this attribute if a plugin sample is deprecated with a release of the IntelliJ Platform.
+* `<depends>` Include at least one dependency with the module `com.intellij.modules.platform` to indicate basic plugin compatibility with IntelliJ Platform-based products.
+  Add `<depends>` elements containing module FQNs as needed to describe more specialized [Compatibility with Multiple Products](/basics/getting_started/plugin_compatibility.md), and any other [Plugin Dependencies](/basics/plugin_structure/plugin_dependencies.md). 
+* `<description>` is a concise explanation of what is being demonstrated and how a user would access the functionality.
+* `<change-notes>` is an ordered list by version numbers with a brief description of changes for each version.
+* `<vendor>` Set the value to `IntelliJ Platform SDK`.
+  Set the attributes:
+  * `email` omit this attribute. 
+  * `url` to the JetBrains plugin repository `"https://plugins.jetbrains.com"`
+* The remainder of the [plugin configuration elements](/basics/plugin_structure/plugin_configuration_file.md) should only appear if they are needed by a specific plugin.
+
+## Testing
+IntelliJ Platform SDK code samples should be built and tested against the `since-build` version.
+
+Code samples should build cleanly, with no warnings or errors, and new code samples should pass all default IntelliJ IDEA code inspections.
+
+Testers should complete the following checklist. 
+Here the term "IDE" means the IntelliJ Platform-based IDE in which the plugin is designed to run:
+* The plugin should load in the IDE.
+* The correct information about the plugin should display in the **Preferences \| Plugins** panel.
+* If applicable, the plugin UI such as tool windows, menu additions, etc. should display correctly.
+* The functionality of the plugin should be tested with a sample file.
+* If applicable, the plugin should pass unit tests.
\ No newline at end of file
diff --git a/tutorials/build_system.md b/tutorials/build_system.md
index 38938c22e..2f42d353d 100644
--- a/tutorials/build_system.md
+++ b/tutorials/build_system.md
@@ -4,13 +4,19 @@ title: Building plugins with Gradle
 
 The [gradle-intellij-plugin](https://github.com/JetBrains/gradle-intellij-plugin) Gradle plugin is the recommended
 solution for building IntelliJ plugins. The plugin takes care of the dependencies of your plugin project - both the
-base IDE and the other plugins that your plugin may depend on.
- 
+base IDE and other plugin dependencies.
+
 It also provides tasks to run the IDE with your plugin and to publish your plugin to the [JetBrains plugins repository](/plugin_repository/index.md). To make sure that your plugin is not affected by [API changes](/reference_guide/api_changes_list.md)
 which may happen between major releases of the platform, you can easily build your plugin against many versions
 of the base IDE.
 
-The following tutorial refers to materials that can be found in the included [gradle_plugin_demo](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/gradle_plugin_demo) project. Below are a series of guides to configuring Gradle support.
+> **WARNING** When adding additional repositories to your Gradle build script, make sure to always use HTTPS protocol.
 
-*  [1. Getting Started](build_system/prerequisites.md)
-*  [2. Deploying a plugin](build_system/deployment.md)
\ No newline at end of file
+> **Note** Please make sure to always upgrade to the latest version of `gradle-intellij-plugin`.
+Follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases). 
+ 
+The following tutorial refers to materials that can be found in the included [gradle_plugin_demo](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/gradle_plugin_demo) project. 
+Below are a series of guides to developing and deploying Gradle-based IntelliJ Platform Plugins:  
+*  [1. Getting Started with Gradle-Based Plugins](build_system/prerequisites.md)
+*  [2. Configuring Gradle-Based Plugins](build_system/gradle_guide.md)
+*  [3. Deploying a Plugin with Gradle](build_system/deployment.md)
\ No newline at end of file
diff --git a/tutorials/build_system/deployment.md b/tutorials/build_system/deployment.md
index 6dc4e5000..a71e55183 100644
--- a/tutorials/build_system/deployment.md
+++ b/tutorials/build_system/deployment.md
@@ -5,6 +5,8 @@ title: Publishing Plugins with Gradle
 Once you have configured Gradle support, you can automatically build and deploy your plugin to the [JetBrains Plugin Repository](https://plugins.jetbrains.com). To do so, you 
 will need to have already published the plugin to the plugin repository. For detailed information, please see the guide to [publishing a plugin](../../basics/getting_started/publishing_plugin.md).
 
+> **WARNING** When adding additional repositories to your Gradle build script, make sure to always use HTTPS protocol.
+
 ### 2.0 Add your account credentials
 
 In order to deploy a plugin to the plugin repository, you will first need to supply your JetBrains Account credentials. 
diff --git a/tutorials/build_system/gradle_guide.md b/tutorials/build_system/gradle_guide.md
index a6677c5b6..f3b1fc5a3 100644
--- a/tutorials/build_system/gradle_guide.md
+++ b/tutorials/build_system/gradle_guide.md
@@ -57,11 +57,8 @@ Using the corresponding JetBrains Runtime is also the default, so for this use c
 
 #### Running Against Alternate Versions and Types of IntelliJ Platform-Based IDEs
 The IntelliJ Platform IDE used for the Development Instance can be different from that used to build the plugin project.
-Two Gradle plugin attributes can be set to the path of an alternate (different version or non-IDEA) IntelliJ Platform-based IDE to control the configuration used for the IDE Development Instance:
-* Setting the [Running DSL](https://github.com/jetbrains/gradle-intellij-plugin#running-dsl) attribute `runIde.ideaDirectory` will define an IDE to be used for the Development Instance in that single `runIde` task.
-* Setting the Setup DSL attribute `intellij.alternativeIdePath` will define an IDE as the default value for all `runIdea.ideaDirectory` attributes of all `runIde` tasks, including `runIde.buildSearchableOptions`.
-  It also sets the default IDE configuration for running tests and retrieving versions of JetBrains Runtimes.
-  This attribute is commonly used when running the plugin in an [alternate IntelliJ Platform-based IDE](/intro/intellij_platform.md#ides-based-on-the-intellij-platform).
+Setting the [Running DSL](https://github.com/jetbrains/gradle-intellij-plugin#running-dsl) attribute `runIde.ideaDirectory` will define an IDE to be used for the Development Instance in that single `runIde` task.
+This attribute is commonly used when running or debugging a plugin in an [alternate IntelliJ Platform-based IDE](/intro/intellij_platform.md#ides-based-on-the-intellij-platform).
 
 #### Running Against Alternate Versions of the JetBrains Runtime
 Every version of the IntelliJ Platform has a corresponding version of the [JetBrains Runtime](/basics/ide_development_instance.md#using-a-jetbrains-runtime-for-the-development-instance).
@@ -87,19 +84,22 @@ The Gradle plugin version is defined in the `plugins {}` section of a project's
 The Gradle version is in defined in a project's `gradle-wrapper.properties`.
 
 ### Patching the Plugin Configuration File
-A plugin project's `plugin.xml` file has values replaced from the attributes of the [Patching DSL](https://github.com/jetbrains/gradle-intellij-plugin#patching-dsl).
-With the exception of the `since-build` and `until-build` attributes of the `<idea-version>` element, all of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's `plugin.xml` file.
-The `since-build` and `until-build` substitution can be inhibited by setting `intellij.updateSinceUntilBuild` to `false`.
-Substitution of at least the default value for the other attributes cannot be inhibited.
+A plugin project's `plugin.xml` file has element values that are "patched" at build time from the attributes of the `patchPluginXml` ([Patching DSL](https://github.com/jetbrains/gradle-intellij-plugin#patching-dsl)) task. 
+As many as possible of the attributes in the Patching DSL will be substituted into the corresponding element values in a plugin project's `plugin.xml` file:
+* If a `patchPluginXml` attribute default value is defined, the attribute value will be patched in plugin.xml _regardless of whether the `patchPluginXml` task appears in the `build.gradle` file_.
+  * For example, the default values for the attributes `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` are defined based on the declared (or default) value of `intellij.version`.
+    So by default `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` are substituted into the `<idea-version>` element's `since-build` and `until-build` attributes in the `plugin.xml` file.
+* If a `patchPluginXml` attribute value is explicitly defined, the attribute value will be substituted in `plugin.xml`.
+  * If both `patchPluginXml.sinceBuild` and `patchPluginXml.untilBuild` attributes are explicitly set, both are substituted in `plugin.xml`. 
+  * If one attribute is explicitly set (e.g. `patchPluginXml.sinceBuild`) and one is not (e.g. `patchPluginXml.untilBuild` has default value,) both attributes are patched at their respective (explicit and default) values.
 
 A best practice to avoid confusion is to replace the elements in `plugin.xml` that will be patched by the Gradle plugin with a comment.
 That way the values for these parameters do not appear in two places in the source code.
 The Gradle plugin will add the necessary elements as part of the patching process.
-For those attributes that contain descriptions such as `changeNotes` and `pluginDescription`, a `CDATA` block is not necessary when using HTML elements.
+For those `patchPluginXml` attributes that contain descriptions such as `changeNotes` and `pluginDescription`, a `CDATA` block is not necessary when using HTML elements.
 
 As discussed in [Components of a Wizard-Generated Gradle IntelliJ Platform Plugin](prerequisites.md#components-of-a-wizard-generated-gradle-intellij-platform-plugin), the Gradle properties `project.version`, `project.group`, and `rootProject.name` are all generated based on the input to the Wizard.
 However, the IntelliJ IDEA Gradle plugin does not combine and substitute those Gradle properties for the default `<id>` and `<name>` elements in the `plugin.xml` file.
-There is no IntelliJ Platform-related reason these Gradle properties must equal the corresponding `plugin.xml` `<id>` and `<name>` elements, but synchronizing them is considered a best practice to avoid confusion.
 
 ### Publishing with the Gradle Plugin
 Please review the [Publishing Plugins with Gradle](deployment.md) page before using the [Publishing DSL](https://github.com/jetbrains/gradle-intellij-plugin#publishing-dsl) attributes.
@@ -138,7 +138,7 @@ It will be helpful to review the [PhpStorm Plugin Development](/products/phpstor
   That enables running and debugging the plugin in the target (e.g., PhpStorm) application.
   The choice of application to use for the IDE Development Instance is configured using the Gradle plugin attribute `intellij.alternativeIdePath`.
 
-The snippet below is an example of configuring the Setup DSL in a `build.gradle` file to develop a plugin targeted at PhpStorm. 
+The snippet below is an example of configuring the Setup and Running DSLs in a `build.gradle` file to develop a plugin targeted at PhpStorm. 
 The configuration uses IntelliJ IDEA Community Edition v2019.1.2 (build 191.7141.44) as the IntelliJ Platform against which the plugin project is built.
 It uses PhpStorm v2019.1.2 (build 191.7141.52) as the IDE Development Instance in which the plugin project is run and debugged.
 ```groovy
@@ -148,10 +148,10 @@ It uses PhpStorm v2019.1.2 (build 191.7141.52) as the IDE Development Instance i
     type 'IC'              // Use IntelliJ IDEA CE as basis of IntelliJ Platform   
     // Require the Php plugin, must be compatible with target v2019.1.2
     plugins 'com.jetbrains.php:191.6707.66'     
-    // Path to installed v2019.1.2 PhpStorm to use as IDE Development Instance
-    alternativeIdePath '/Applications/apps/PhpStorm/ch-0/191.7141.52/PhpStorm.app/Contents'
+  }
+  
+  runIde {
+      // Path to installed v2019.1.2 PhpStorm to use as IDE Development Instance
+      ideaDirectory '/Applications/apps/PhpStorm/ch-0/191.7141.52/PhpStorm.app/Contents'
   }
 ```
-  
-  
-  
diff --git a/tutorials/build_system/prerequisites.md b/tutorials/build_system/prerequisites.md
index 48ee3649a..53b2f5c9b 100644
--- a/tutorials/build_system/prerequisites.md
+++ b/tutorials/build_system/prerequisites.md
@@ -2,116 +2,201 @@
 title: Getting Started with Gradle
 ---
 
-Adding Gradle build support to an IntelliJ Platform Plugin requires a recent distribution of the Gradle build system and IntelliJ IDEA (Community or Ultimate).
+Gradle is the preferred solution for creating IntelliJ Platform plugins.
+The IntelliJ IDEA Ultimate and Community editions bundle the necessary plugins to support Gradle-based development.
+These IntelliJ IDEA plugins are _Gradle_ and _Plugin DevKit_, which are enabled by default.
+To verify these plugins are installed and enabled, see the help section about [Managing Plugins](https://www.jetbrains.com/help/idea/managing-plugins.html).
 
-### 1.0 Download and Install IntelliJ IDEA
+* bullet list
+{:toc}
 
-Download and install either IntelliJ IDEA Ultimate or the IntelliJ IDEA Community Edition.
 
-### 1.1 Ensure that 'Gradle' and 'Plugin DevKit' Plugins are Enabled
+> **WARNING** When adding additional repositories to your Gradle build script, make sure to use HTTPS always.
 
-You can verify that the plugins are enabled by visiting **Settings \| Plugins**.
+## Creating a Gradle-Based IntelliJ Platform Plugin with New Project Wizard
+IntelliJ IDEA supports creating new Gradle-based IntelliJ Platform plugin projects using the [New Project Wizard](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle).
+The Wizard creates all the necessary project files based on a few template inputs.
 
-![Ensure the Gradle plugin is enabled](img/step0_gradle_enabled.png){:width="858px"}
+Before creating a new Gradle project, familiarize yourself with the IntelliJ IDEA help topic [Creating a new Gradle project](https://www.jetbrains.com/help/idea/getting-started-with-gradle.html#create_gradle_project), which is a tutorial for creating general Gradle projects in IntelliJ IDEA.
+This page emphasizes the steps in the process for creating IntelliJ Platform plugin projects that are Gradle-based.
 
-### 1.2 Create a Plugin Project from Scratch
+Launch the [New Project Wizard](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle).
+It guides you through the Gradle project creation process with four screens.
 
-IntelliJ IDEA supports automatically creating new plugin projects using Gradle, with all the necessary `build.gradle`
-setup performed automatically. This can also be used to convert an existing plugin to Gradle, if Gradle is not able to 
-convert the existing project - in this case, you need to copy over the sources to the new project.
-
-To do so, create a new project in IntelliJ IDEA by opening **File \| New... \| Project**, and select Gradle from the dialog box.
-In the "Additional Libraries and Frameworks" page, check "IntelliJ Platform Plugin".
+### New Project Configuration Screen
+On the first screen, the type of project is configured:
+* From the _product category_ pane on the left, choose _Gradle_.
+* Specify the _Project SDK_ based on the Java 8 JDK.
+  This SDK will be the default JRE used to run Gradle, and the JDK version used to compile the plugin Java source.
+  Based on the Project SDK, the IntelliJ IDEA Gradle Plugin will download the corresponding version of the IntelliJ Platform-based IDE automatically.
+* In the _Additional Libraries and Frameworks_ panel, select _Java_ and _IntelliJ Platform Plugin_, then click _Next_.
 
 ![Select the Gradle facet in the Project Creation Wizard](img/step1_new_gradle_project.png){:width="800px"}
 
-The Project Creation Wizard will now guide you through the Gradle project creation process. You will need to specify a Group ID, Artifact ID, and Version:
+### Project Naming Screen
+On this, the second screen of the Wizard, specify a [Group ID, Artifact ID, and plugin Version](https://www.jetbrains.com/help/idea/gradle.html#project_create_gradle) using [Maven naming](https://maven.apache.org/guides/mini/guide-naming-conventions.html) conventions.
+* _Group ID_ is typically a Java package name, and it is used for the Gradle property `project.group` value in the project's `build.gradle` file.
+  For this example, enter "com.your.company".
+* _Artifact ID_ is the default name of the project JAR file (without version).
+  It is also used for the Gradle property `rootProject.name` value in the project's `settings.gradle` file.
+  For this example, enter "my_gradle_plugin".
+* _Version_ is used for the Gradle property `project.version` value in the `build.gradle` file. 
+  For this example, enter "1.0".
 
-![Specify the Group, Artifact, and Version IDs](img/step2_group_artifact_version.png){:width="800px"}
+Click _Next_ to continue. 
 
-It’s recommended to select the `Use default gradle wrapper` option, that way IntelliJ IDEA will install everything you need to run Gradle tasks itself.
+### Gradle Settings Screen
+The third screen prompts for Gradle-specific settings. 
+All of these settings can be changed once the project is created via **Settings \| Build, Execution, Deployment \| Build Tools \| Gradle**. 
+Select the [default settings](https://www.jetbrains.com/help/idea/gradle-settings.html) and click _Next_ to continue.
 
-Finally, specify a JVM Gradle will use, it can be the Project JDK. You also configure this path once the project is created via **Settings \| Build, Execution, Deployment \| Build Tools \| Gradle**.
+### Project Name and Location Screen
+The final Wizard screen is for setting the [project name and location](https://www.jetbrains.com/help/idea/project-name-and-location.html#Project_Name_and_Location.xml).
+The _Project name_ is pre-filled with the [Artifact ID](#project-naming-screen).
 
-![Verify the JVM is the correct version](img/step3_gradle_config.png){:width="800px"}
+Note the choice of _Project format_ under _More Settings_ is somewhat superfluous.
+Although an `.idea` directory or `.ipr` file is generated as the project is created and built, it is Gradle and the IntelliJ IDEA Gradle plugin that control many aspects of the project.  
 
-### 1.3 Configuring a Gradle Plugin Project
-Support for Gradle-based plugin projects is provided by the IntelliJ Platform `gradle-intellij-plugin`.
+Click _Finish_.
 
-> **Note** Please make sure to always upgrade to latest version of `gradle-intellij-plugin` plugin, follow releases on [GitHub](https://github.com/JetBrains/gradle-intellij-plugin/releases). 
+### Components of a Wizard-Generated Gradle IntelliJ Platform Plugin
+For the [example](#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard) `my_gradle_plugin`, the New Project Wizard creates the directory content shown below:
+* The default IntelliJ Platform `build.gradle` file.
+  The contents are further discussed below.
+* The Gradle Wrapper files, and in particular the `gradle-wrapper.properties` file, which specifies the version of Gradle to be used to build the plugin.
+  If needed, the IntelliJ IDEA Gradle plugin will download the version of Gradle specified in this file.
+* The `settings.gradle` file, containing a definition of the `rootProject.name`.
+* The `META-INF` directory under the default `main` [SourceSet](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) contains the plugin [configuration file](/basics/plugin_structure/plugin_configuration_file.md).
 
-See the [Gradle plugin README](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md#gradle) for more information. 
-For example, to configure the **Sandbox Home** directory's location include the following in the project's `build.gradle` file:
-```groovy
-intellij {
-  sandboxDirectory = "$project.buildDir/myCustom-sandbox"
-}
+```text
+  my_gradle_plugin/
+    build.gradle
+    gradle/
+      wrapper/
+        gradle-wrapper.jar
+        gradle-wrapper.properties
+    gradlew
+    gradlew.bat
+    settings.gradle
+    src/
+      main
+        java/
+        resources/
+          META-INF/
+            plugin.xml
+      test
+        java/
+        resources/
 ```
-See the [IDE Development Instances](/basics/ide_development_instance.md) 
-page for more information about default Sandbox Home directory locations and contents.
- 
-### 1.4 Add Gradle Support to an Existing Plugin 
 
-To add Gradle support to an existing plugin project, create a `build.gradle` file under the root directory, with at least the following contents:
+The New Project Wizard produces the `my_gradle_plugin` project `build.gradle` file shown below:
+* There is no explicit `buildscript{}` in the file.
+  The IntelliJ IDEA Gradle plugin dynamically creates a `buildscript{}`.
+* Two plugins to Gradle are explicitly declared:
+  * The [Gradle Java](https://docs.gradle.org/current/userguide/java_plugin.html) plugin.
+  * The [IntelliJ IDEA Gradle plugin](https://github.com/JetBrains/gradle-intellij-plugin/).
+* The _Group ID_ from the Wizard [Project Naming Screen](#project-naming-screen) is the `project.group` value.
+* The _Version_ from the Wizard [Project Naming Screen](#project-naming-screen) is the `project.version` value.
+* The `sourceCompatibility` line is injected to enforce using Java 8 JDK to compile Java source.
+* The only comment in the file is a link to the [`README.md`](https://github.com/JetBrains/gradle-intellij-plugin/blob/master/README.md) for the IntelliJ IDEA Gradle plugin, which is a reference for the DSLs defined by the plugin.
+* The value of the Setup DSL attribute `intellij.version` specifies the version of the IntelliJ Platform to be used to build the plugin.
+  It defaults to the version of IntelliJ IDEA that was used to run the New Project Wizard.
+* The value of the Patching DSL attribute `patchPluginXml.changeNotes` is set to place holder text.
 
-```groovy
-buildscript {
-    repositories {
-        mavenCentral()
+```text
+  plugins {
+      id 'java'
+      id 'org.jetbrains.intellij' version '0.4.9'
+  }
+  
+  group 'com.your.company'
+  version '1.0' 
+  sourceCompatibility = 1.8
+  
+  repositories {
+      mavenCentral()
+  } 
+  dependencies {
+      testCompile group: 'junit', name: 'junit', version: '4.12'
+  }
+  
+  // See https://github.com/JetBrains/gradle-intellij-plugin/
+  intellij {
+      version '2019.1'
+  }
+  patchPluginXml {
+      changeNotes """
+        Add change notes here.<br>
+        <em>most HTML tags may be used</em>"""
+  }
+```
+
+#### Plugin Gradle Properties and Plugin Configuration File Elements
+The Gradle properties `rootProject.name` and `project.group` will not, in general, match the respective `plugin.xml` elements `<name>` and `<id>`.
+There is no IntelliJ Platform-related reason they should as they serve different functions.
+The `<name>` element can have nothing to do with the content root, and often is more explanatory than the `rootProject.name`.
+The `<id>` is a unique identifier over all plugins, typically a concatenation of the Maven `groupId` and `artifactId`; the default Gradle `project.group` property is only the `groupId`.
+
+
+## Adding Gradle Support to an Existing DevKit-Based IntelliJ Platform Plugin
+Converting a DevKit-based plugin project to a Gradle-based plugin project can be done using the New Project Wizard to create a Gradle-based project around the existing DevKit-based project: 
+* Ensure the directory containing the DevKit-based IntelliJ Platform plugin project can be fully recovered if necessary.
+* Delete all the artifacts of the DevKit-based project:
+  * `.idea` directory
+  * IML file
+  * `out` directory
+* Arrange the existing source files within the project directory in Gradle [SourceSet](https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_project_layout) format. 
+* Use the New Project Wizard as though creating a [new Gradle project](#creating-a-gradle-based-intellij-platform-plugin-with-new-project-wizard) from scratch.
+* On the [Project Naming Screen](#project-naming-screen) set the values to:
+  * GroupID to the existing package in the initial source set.
+  * ArtifactID to the name of the existing plugin.
+  * Version to the same as the existing plugin.
+* On the [Project Name and Location Screen](#project-name-and-location-screen) set the values to:
+  * _Project name_ to the name of the existing plugin. 
+    (It should be pre-filled from the _ArtifactID_)
+  * Set the _Project location_ to the directory of the existing plugin.
+* Click _Finish_ to create the new Gradle-based plugin.
+* [Add more modules](https://www.jetbrains.com/help/idea/gradle.html#gradle_add_module) using Gradle [_Source Sets_](https://www.jetbrains.com/help/idea/gradle.html#gradle_source_sets) as needed.
+
+
+## Running a Simple Gradle-Based IntelliJ Platform Plugin
+Before running [`my_gradle_project`](#components-of-a-wizard-generated-gradle-intellij-platform-plugin), some code needs to be added to provide simple functionality.
+* Using the code below, add a `HelloAction.java` class to the `src/main/java/` folder.
+  For the sake of simplicity, no Java package is being used in this example. 
+
+```java
+  import com.intellij.openapi.actionSystem.*;
+  import com.intellij.openapi.project.Project;
+  import com.intellij.openapi.ui.Messages;
+  
+  public class HelloAction extends AnAction {
+    public HelloAction() {
+      super("Hello");
     }
-}
-
-plugins {
-    id "org.jetbrains.intellij" version "0.4.7"
-}
-
-apply plugin: 'idea'
-apply plugin: 'org.jetbrains.intellij'
-apply plugin: 'java'
-
-intellij {
-    version 'IC-2016.3' //IntelliJ IDEA 2016.3 dependency; for a full list of IntelliJ IDEA releases please see https://www.jetbrains.com/intellij-repository/releases
-    plugins 'coverage' //Bundled plugin dependencies
-    pluginName 'plugin_name_goes_here'
-}
-
-group 'org.jetbrains'
-version '1.2' // Plugin version
+  
+    public void actionPerformed(AnActionEvent event) {
+      Project project = event.getProject();
+      Messages.showMessageDialog(project, "Hello world!", "Greeting", Messages.getInformationIcon());
+    }
+  }
 ```
 
-Then, with the Gradle executable on your system `PATH`, execute the following commands on your system's command line:
+* Add the code below to the `<actions>` section of the `plugin.xml` file: 
 
+```xml
+  <group id="MyPlugin.SampleMenu" text="Greeting" description="Greeting menu">
+    <add-to-group group-id="MainMenu" anchor="last"/>
+    <action id="Myplugin.Textboxes" class="HelloAction" text="Hello" description="Says hello"/>
+  </group>
 ```
-gradle cleanIdea idea
-```
-
-This will clean any existing IntelliJ IDEA configuration files and generate a new Gradle build configuration recognized by IntelliJ IDEA. Once your project refreshes, you should be able to view the Gradle tool window displayed under **View \| Tool Windows \| Gradle**. This indicates that IntelliJ IDEA recognizes the Gradle facet.
-
-### 1.5 Running a Simple Plugin
-
-Now add a new `HelloAction` class to the Java folder, and `plugin.xml` and `pluginIcon.svg` files in the `META-INF` folder.
-For more information about `pluginIcon.svg` files, see the [Plugin Icon](/basics/plugin_structure/plugin_icon_file.md) page.
-
-![Gradle directory structure](img/gradle_directory_structure.png){:width="374px"}
-
-```java
-{% include /code_samples/gradle_plugin_demo/src/main/java/HelloAction.java %}
-```
-
-```java
-{% include /code_samples/gradle_plugin_demo/src/main/resources/META-INF/plugin.xml %}
-```
-
-Open the Gradle tool window and search for `runIde` task. If it’s not in the list, please hit `Refresh` button on the top. Double-click on it to run it.
-
+ 
+* Open the Gradle tool window and search for the `runIde` task. 
+  If it’s not in the list, hit the [Refresh](https://www.jetbrains.com/help/idea/jetgradle-tool-window.html#1eeec055) button at the top of the Gradle window. 
+  Or [Create a new Gradle Run Configuration](https://www.jetbrains.com/help/idea/create-run-debug-configuration-gradle-tasks.html).
+  
 ![Gradle Tool Window](img/gradle_tasks_in_tool_window.png){:width="398px"}
+   
+* Double-click on the _runIde_ task to execute it.
+  See the IntelliJ IDEA help for more information about [Working with Gradle tasks](https://www.jetbrains.com/help/idea/gradle.html#96bba6c3).
 
-Or add a new Gradle Run Configuration, configured like so:
-
-![Gradle Run Configuration](img/gradle_run_config.png){:width="800px"}
-
-Launch the new Gradle Run Configuration. From the Run Window, the following output should be visible.
-
-![Gradle task output](img/launched.png){:width="800px"}
-
-Finally, when the IDE launches, there should be a new menu to the right of the **Help** menu. Your plugin is now configured on Gradle.
+Finally, when `my_gradle_plugin` launches in the IDE development instance, there should be a new **Greeting** main menu to the right of the **Help** menu.