Move description

This site is the new docs site currently being tested. For the actual docs in use please go to https://www.jenkins.io/doc.

To help administrators decide if a plugin is relevant for them, each plugin should provide a short description which is then shown in plugin manager and on the plugin site. The preferred location for the plugin description is in the file src/main/resources/index.jelly. In the past it was also possible to provide it using the description tag in plugin POM, but recent versions of the parent POM require the preferred location and will fail to compile if the plugin description is not available from index.jelly in the expected directory.

Copy the contents of the description tag from the POM file to src/main/resources/index.jelly.

Some plugins do not currently provide description at all or use description copied from the hello-world sample plugin. For such plugins you have to write the description yourself. Such plugins are listed in https://issues.jenkins.io/browse/JENKINS-68300.

When such a conversion is needed, the Maven build process will frequently output a message like:

[ERROR] Failed to execute goal maven-hpi-{plugin}hpi (default-hpi) on
project your-plugin: Missing target/classes/index.jelly. Delete any
<description> from pom.xml and create src/main/resources/index.jelly:

Create a branch

In a local copy of your fork of the plugin repository create a git branch for your work with the command:

git checkout -b {task-identifier} master

Compile and test to check the transition is needed

Compile the plugin (with a recent parent pom) and confirm that the description transition warning message is displayed:

mvn -ntp clean verify
[ERROR] Failed to execute goal maven-hpi-{plugin}hpi (default-hpi) on
project your-plugin: Missing target/classes/index.jelly. Delete any
<description> from pom.xml and create src/main/resources/index.jelly:

If the warning message is not displayed and the plugin is using the most recent parent pom, then no transition is necessary.

Move description to src/main/resources/index.jelly

Remove the <description> tag and its value from the POM. Create the src/main/resources/index.jelly file and insert the description as follows:

<?jelly escape-by-default='true'?>
<div>
Insert your plugin description here
</div>

Review the change with the command:

git diff
diff --git a/src/main/resources/index.jelly b/src/main/resources/index.jelly
new file mode 100644
index 0000000..9434d10
--- /dev/null
+++ b/src/main/resources/index.jelly
@@ -0,0 +1,4 @@
+<?jelly escape-by-default='true'?>
+<div>
+Insert your plugin description here
+</div>

Compile the updated code with the command:

mvn clean verify

Create a pull request

Commit that change:

git add {modified-files}
git commit -m "{task-description}"

Push the change to GitHub:

git push origin --set-upstream {task-identifier}

Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for '{task-identifier}' on GitHub by visiting:
remote: https://github.com/user/your-plugin/pull/new/{task-identifier}
remote:
To github.com:user/your-plugin.git
 * [new branch]      {task-identifier} -> {task-identifier}
Branch '{task-identifier}' tracking remote branch '{task-identifier}'.

Notice that the output of the command includes the URL, which can be used to open a pull request. Copy that URL in your web browser and submit a pull request.