Skip to content

Latest commit

 

History

History
163 lines (143 loc) · 10.3 KB

sdk_code_guidelines.md

File metadata and controls

163 lines (143 loc) · 10.3 KB
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 and License documents. For information about contributing to the IntelliJ Platform itself visit Contributing to the IntelliJ Platform.

  • 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 file. See the Plugin Gradle Properties section for more information about the distinction.

Plugin Copyright Statements

Use the standard intellij-community copyright notice in all sample plugins authored by JetBrains:

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 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.

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. 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. 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 section for how these Gradle properties relate to the elements in plugin.xml.
  • Add the following statements to the Setup DSL (intellij{}) section: 
        // 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 (patchPluginXml{}) section. It is not needed in SDK samples.
  • Add the javadoc task to build documentation for the code sample: 
      // Force javadoc rebuild before jar is built
  jar.dependsOn javadoc

plugin.xml Conventions

A consistent structure for the plugin.xml 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.
  • <name> The name value does not have to match the Plugin Name. 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, and any other Plugin Dependencies.
  • <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 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.