mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-30 18:27:49 +08:00
Final draft updatePlugins.
This commit is contained in:
JohnHake
parent
157decc6a8
commit
d6180fd8a6
@ -24,7 +24,7 @@
|
||||
* [Running and Debugging a Plugin](basics/getting_started/running_and_debugging_a_plugin.md)
|
||||
* [Deploying a Plugin](basics/getting_started/deploying_plugin.md)
|
||||
* [Publishing a Plugin](basics/getting_started/publishing_plugin.md)
|
||||
* [updatePlugins File](basics/getting_started/update_plugins_format.md)
|
||||
* [Enterprise Plugin Repositories](basics/getting_started/update_plugins_format.md)
|
||||
* [Plugin Structure](basics/plugin_structure.md)
|
||||
* [Plugin Content](basics/plugin_structure/plugin_content.md)
|
||||
* [Plugin Class Loaders](basics/plugin_structure/plugin_class_loaders.md)
|
||||
|
||||
@ -11,146 +11,64 @@ you will need to:
|
||||
## Describing Your Plugins in an updatePlugins File
|
||||
Every enterprise plugin repository must have at least one `updatePlugins.xml` file to describe the latest compatible version
|
||||
for every hosted plugin. The description in `updatePlugins.xml` is used by JetBrains IDEs to locate plugins by attributes
|
||||
such as vendor, functional category, version, etc. These attributes are displayed by JetBrains IDEs to help users select or upgrade plugins.
|
||||
such as id, IDE version, and plugin version. These attributes are displayed by JetBrains IDEs to help users select or upgrade plugins.
|
||||
The description also tells the JetBrains IDE where to download the plugin itself.
|
||||
|
||||
@chkrv - The following description of mapping updatePlugins-*.xml files to unique URLs assumes JetBrains IDEs can't select
|
||||
the correct file based on the naming convention. Is that correct?
|
||||
**@Q:** are multiple updatePlugin files really needed for minor releases? Or is this just best practice?
|
||||
|
||||
An enterprise plugin repository's `updatePlugins.xml` file is constructed and maintained by the administrator of
|
||||
the repository. More than one `updatePlugins.xml` file will be required if consumers of the enterprise repository are using more
|
||||
the repository. More than one `updatePlugins.xml` file may be required if consumers of the enterprise repository are using more
|
||||
than one version of a JetBrains IDE. For example `updatePlugins-182.xml`, `updatePlugins-183.xml` for IntelliJ IDEA 2018.2 and 2018.3 respectively.
|
||||
Each `updatePlugins-*.xml` file will have a unique, IDE version-specific URL that is added to the JetBrains IDE
|
||||
Each `updatePlugins-*.xml` file will have a unique URL that is added to the JetBrains IDE
|
||||
[Repository Settings/Preferences](https://www.jetbrains.com/help/idea/managing-plugins.html#repos).
|
||||
|
||||
### The Format of an updatePlugins File
|
||||
The overall structure of a `updatePlugins.xml` file is:
|
||||
The format of an `updatePlugins.xml` file is simply a list of sequential elements that describe each plugin:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<plugin-repository>
|
||||
<ff>"category_1"</ff>
|
||||
<category name="category_1">
|
||||
<!-- One or more plug descriptions -->
|
||||
<idea-plugin></idea-plugin>
|
||||
</category>
|
||||
<ff>"category_2"</ff>
|
||||
<category name="category_2">
|
||||
<!-- One or more plug descriptions -->
|
||||
<idea-plugin></idea-plugin>
|
||||
</category>
|
||||
<ff>"category_3"</ff>
|
||||
<category name="category_3">
|
||||
<!-- One or more plug descriptions -->
|
||||
<idea-plugin></idea-plugin>
|
||||
</category>
|
||||
<ff>"category_n"</ff>
|
||||
<category name="category_n">
|
||||
<!-- One or more plug descriptions -->
|
||||
<idea-plugin></idea-plugin>
|
||||
</category>
|
||||
</plugin-repository>
|
||||
```
|
||||
|
||||
#### Describing Categories of Plugins
|
||||
Within the `<plugin-repository>` elements is a sequential list of categories of plugins available in the repository. The
|
||||
valid plugin categories are listed at the bottom of product-specific pages at the
|
||||
[JetBrains Plugin Repository](https://plugins.jetbrains.com/idea). For example,
|
||||
"Administration Tools", "Graphics", "Navigation", etc.
|
||||
|
||||
Each category section begins with the `<ff></ff>` and `<category>` elements, and ends with a `</category>` element. Note:
|
||||
* The `<ff></ff>` elements only appear at the start of a category.
|
||||
* The string contained withing the `<ff>` elements must exactly match the `name` attribute of the `<category>` element.
|
||||
* Categories should only appear if at least one plugin exists in that category.
|
||||
|
||||
|
||||
#### Describing Individual Plugins
|
||||
Each available plugin is described between `<idea-plugin></idea-plugin>` elements.
|
||||
As shown below, not all elements and attributes are required because some are specific
|
||||
to the [JetBrains Plugin Repository](https://plugins.jetbrains.com).
|
||||
|
||||
```xml
|
||||
<!--
|
||||
The idea-plugin element is required to identify this plugin for the plugin repository.
|
||||
downloads - an integer describing the number of times this plugin has been downloaded (optional)
|
||||
size - of JAR as an integer # of Bytes (required)
|
||||
url - full path to download JAR directly (required)
|
||||
date - latest revision date of plugin in Unix aka POSIX time format (optional)
|
||||
<!--
|
||||
The <plugins> element contains the description of the plugins available at this repository. Required.
|
||||
-->
|
||||
<idea-plugin downloads='3298' size='8454' url='https://download.mycompany.com/mypluginname.jar' date='1429634833000' >
|
||||
<!--
|
||||
The name and id elements are required. The name is displayed on the plugin repository.
|
||||
The id is used by JetBrains IDEs to uniquely identify a plugin
|
||||
-->
|
||||
<name>My Plugin Name</name>
|
||||
<id>fully.qualified.id.of.this.plugin</id>
|
||||
<!-- Description is optional. It is displayed on the plugin repository. -->
|
||||
<description><![CDATA[A description of the plugin. Can include html tags.]]></description>
|
||||
<!-- The version element is required, and is used to signal upgrade availability to users -->
|
||||
<version>major.minor.update</version>
|
||||
<!--
|
||||
The vendor element is required.
|
||||
email - support or general contact (optional)
|
||||
url - company address (optional)
|
||||
-->
|
||||
<vendor email='support.me@mycompany.com' url='https://mycompany.com'>Company name or developer name</vendor>
|
||||
<!--
|
||||
The idea-version element defines the compatibility of this plugin version with IntelliJ Platform builds.
|
||||
It is required.
|
||||
Build numbers are from https://www.jetbrains.org/intellij/sdk/docs/basics/getting_started/build_number_ranges.html
|
||||
since-build - the earliest IntelliJ Platform build supporting this plugin. (required)
|
||||
until-build - the latest IntelliJ Platform build supporting this plugin. (optional)
|
||||
-->
|
||||
<idea-version since-build='131.0' until-build=''/>
|
||||
<!-- Change notes are optional but highly recommended. They are displayed on the plugin repository. -->
|
||||
<change-notes><![CDATA[Description of plugin changes for user. Can include html tags.]]></change-notes>
|
||||
<!--
|
||||
Required if the plugin depends on other plugins.
|
||||
Sets of elements can be repeated for multiple dependencies
|
||||
-->
|
||||
<depends>fully.qualified.id.of.required.plugin</depends>
|
||||
<!--
|
||||
Tag elements are optional, but raise the visibility of a plugin.
|
||||
Sets of elements can be repeated for multiple tags
|
||||
-->
|
||||
<tags>a_category</tags>
|
||||
<!-- Rating is optional. Rating has values 0.0 to 5.0 -->
|
||||
<rating>#.#</rating>
|
||||
</idea-plugin>
|
||||
```
|
||||
|
||||
### Format of updatePlugins File for Private Repositories
|
||||
The `updatePlugins.xml` file for private repositories differs only in that the `<plugins>` element is added
|
||||
and `<plugin>` replaces `<idea-plugin>`. Otherwise, elements permitted between
|
||||
`<idea-plugin>` elements are also permitted between `<plugin>` elements. The example
|
||||
below should be considered the minimum information that should be supplied.
|
||||
|
||||
**Note:** Conflicting information from e.g. `<version>` or `<id>`elements causes the respective
|
||||
`<plugin>` attribute information to be replaced. To avoid mistakes and confusion, using
|
||||
these elements is not recommended with `<plugin>`.
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!-- The plugins element is required. -->
|
||||
<plugins>
|
||||
<!--
|
||||
The plugin element is required.
|
||||
id - used by JetBrains IDEs to uniquely identify a plugin
|
||||
url - path to download JAR directly
|
||||
version - version of this plugin.
|
||||
Each <plugin> element describes one plugin in the repository. Required.
|
||||
id - used by JetBrains IDEs to uniquely identify a plugin. Required. Must match <id> in plugin.xml
|
||||
url - path to download the plugin JAR/ZIP file. Required. Must be Hyper Text Transfer Protocol Secure (HTTPS)
|
||||
version - version of this plugin. Required, must match <version> in plugin.xml
|
||||
-->
|
||||
<plugin id="fully.qualified.id.of.this.plugin" url="https://my_repository.mycompany.com/mypluginname.jar" version="major.minor.update">
|
||||
<plugin id="fully.qualified.id.of.this.plugin" url="https://www.mycompany.com/my_repository/mypluginname.jar" version="major.minor.update">
|
||||
<!--
|
||||
The idea-version element defines the compatibility of this plugin version with IntelliJ Platform builds.
|
||||
It is required.
|
||||
Build numbers are from https://www.jetbrains.org/intellij/sdk/docs/basics/getting_started/build_number_ranges.html
|
||||
since-build - the earliest IntelliJ Platform build supporting this plugin. (required)
|
||||
until-build - the latest IntelliJ Platform build supporting this plugin. (optional)
|
||||
The <idea-version> element must match the same element in plugin.xml. Required.
|
||||
-->
|
||||
<idea-version since-build="181.3" until-build="181.*" />
|
||||
<!-- Description is optional. It is displayed on the plugin repository. -->
|
||||
<description><![CDATA[A description of the plugin. Can include html tags.]]></description>
|
||||
</plugin>
|
||||
<plugin id="id.of.different.plugin" url="https://www.oldserver.com/old_repository/oldplugin.jar" version="major.minor">
|
||||
<idea-version since-build="145" until-build="171" />
|
||||
</plugin>
|
||||
<plugin>
|
||||
<!-- And so on for other plugins... -->
|
||||
</plugin>
|
||||
</plugins>
|
||||
```
|
||||
<br>
|
||||
**Note:**
|
||||
* An `updatePlugins` file must describe at least one plugin, i.e. at least one set of `<plugin></plugin>` elements must
|
||||
appear between the `<plugins></plugins>` elements.
|
||||
* A plugin may be listed only once in an `updatePlugins` file.
|
||||
|
||||
### Optional updatePlugin Elements
|
||||
Can additional elements be added to `updatePlugins.xml`? Yes, but it's advisable only if needed. The additional elements will need
|
||||
to be synchronized with a plugin's `plugin.xml` file.
|
||||
|
||||
During installation the IDE reads the plugin JAR/ZIP file, and thereafter displays more information about the plugin.
|
||||
What additional information might help a user select a plugin when
|
||||
[browsing the enterprise plugin repository](https://www.jetbrains.com/help/idea/managing-plugins.html#repos)
|
||||
before installation? The answer depends on the plugins and repository consumers. Here are the candidate elements:
|
||||
|
||||
| Element | Effects & Requirements |
|
||||
|:-------------------------------------------------------------|:----------------------------|
|
||||
| `<name>`<br>My Plugin Name<br>`</name>` | By default the name of the plugin JAR/ZIP file is displayed before installation. <br>Using the `<name>` element displays the name of the plugin. <br>Contents must match the `<name>` element contents in the plugins's `plugin.xml` file.|
|
||||
| `<description>`<br>My plugin is awesome<br>`</description>` | By default no description for the plugin is displayed before installation. <br>Using the `<description>` element will cause a description to be displayed before installation. <br>Contents must match the `<description>` element contents in the plugins's `plugin.xml` file. <br>Optionally, an enclosing `<![CDATA[ ]]>` element can be used if the description needs to contain HTML tags. |
|
||||
| `<change-notes>`<br>Added cool feature<br>`</change-notes>` | By default no change notes for the plugin are displayed before installation. <br>Using the `<change-notes>` element will cause a description of changes to be displayed before installation. <br>Contents must match the `<change-notes>` element contents in the plugin's `plugin.xml` file. <br>Optionally, an enclosing `<![CDATA[ ]]>` element can be used if the change notes need to contain HTML tags. |
|
||||
|
||||
```
|
||||
@ -2,6 +2,7 @@
|
||||
title: Publishing Plugins with Gradle
|
||||
---
|
||||
|
||||
## Publishing with Gradle to the JetBrains Plugin Repository
|
||||
Once you have configured Gradle support, you can automatically build and deploy your plugin to the [JetBrains Plugin Repository](http://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](http://www.jetbrains.org/intellij/sdk/docs/basics/getting_started/publishing_plugin.html).
|
||||
|
||||
@ -84,6 +85,7 @@ You may also deploy plugins to a release channel of your choosing, by configurin
|
||||
* `beta`: https://plugins.jetbrains.com/plugins/beta/list
|
||||
* `eap`: https://plugins.jetbrains.com/plugins/eap/list
|
||||
|
||||
## Publishing with Gradle to an Enterprise Plugin Repository
|
||||
It is also possible to host an enterprise plugin repository, in which case the URL
|
||||
structure will depend on your hosting address. For more information, please refer to the
|
||||
[Enterprise Plugin Repositories](/basics/getting_started/update_plugins_format.md) documentation.
|
||||
Loading…
x
Reference in New Issue
Block a user