SCM-Manager/docs/en/development/plugins/migrate-plugin-from-v1.md

title

title
Migrate a v1 plugin

Before starting, make sure to read the Plugin Development.

To migrate an existing SCM-Manager 1.x Plugin, you have to do the following steps:

Maven (pom.xml)

• create a separate branch for the new version
• It might be helpful to start and review the old version of the plugin via mvn scmp:run for later reference.
• Import .gitignore & .editorconfig from SCMM
• You might run the build once and review and fix SCMMv1 deprecation warnings. SCMMv2 gets rids of all deprecated classes.
• update the version of the parent artifact (sonia.scm.plugins:scm-plugins) to the minimum version of SCM-Manager 2 you are planning for your plugin
• change the packaging type of your plugin to smp
• remove the sonia.scm.maven:scm-maven-plugin from the pom
• remove servlet-api from the list of dependencies (not always the case)

diff -r a988f4cfb7ab pom.xml
--- a/pom.xml   Thu Dec 10 20:32:26 2015 +0100
+++ b/pom.xml   Tue Oct 30 11:49:35 2018 +0100
@@ -6,13 +6,14 @@
   <parent>
     <artifactId>scm-plugins</artifactId>
     <groupId>sonia.scm.plugins</groupId>
-    <version>1.15</version>
+    <version>2.0.0-rc7</version>
   </parent>
 
   <groupId>sonia.scm.plugins</groupId>
   <artifactId>scm-mail-plugin</artifactId>
   <version>1.6-SNAPSHOT</version>
   <name>scm-mail-plugin</name>
+  <packaging>smp</packaging>
   <url>https://bitbucket.org/sdorra/scm-mail-plugin</url>
   <description>
     The mail plugin provides an api for sending e-mails. 
@@ -28,13 +29,6 @@
   <dependencies>
 
-    <dependency>
-      <groupId>jakarta.servlet</groupId>
-      <artifactId>servlet-api</artifactId>
-      <version>${servlet.version}</version>
-      <scope>provided</scope>
-    </dependency>
 
     <dependency>
       <groupId>org.codemonkey.simplejavamail</groupId>
       <artifactId>simple-java-mail</artifactId>
       <version>2.4</version>
@@ -52,18 +46,6 @@
     <jakartamail.version>1.4.7</jakartamail.version>
   </properties>
   
-  <build>
-    <plugins>
-      
-      <plugin>
-        <groupId>sonia.scm.maven</groupId>
-        <artifactId>scm-maven-plugin</artifactId>
-        <version>1.22</version>
-      </plugin>
-      
-    </plugins>
-  </build>
   
   <repositories>
     
     <repository>

Plugin Descriptor (src/main/resources/META-INF/scm/plugin.xml)

• add the following dtd to the top of the plugin.xml: <!DOCTYPE plugin SYSTEM "https://download.scm-manager.org/dtd/plugin/2.0.0-01.dtd">
• add an scm-version element with the value 2 to the plugin.xml
• remove resources and packages from plugin.xml

diff -r a988f4cfb7ab src/main/resources/META-INF/scm/plugin.xml
--- a/src/main/resources/META-INF/scm/plugin.xml        Thu Dec 10 20:32:26 2015 +0100
+++ b/src/main/resources/META-INF/scm/plugin.xml        Tue Oct 30 11:55:15 2018 +0100
@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<!DOCTYPE plugin SYSTEM "https://download.scm-manager.org/dtd/plugin/2.0.0-01.dtd">
 <!--
 
     Copyright (c) 2010, Sebastian Sdorra
@@ -34,6 +35,8 @@
 
 <plugin>
 
+  <scm-version>2</scm-version>
+
   <information>
     <author>Sebastian Sdorra</author>
     <wiki>https://bitbucket.org/sdorra/scm-manager/wiki/mail-plugin</wiki>
@@ -44,12 +47,4 @@
     <min-version>${project.parent.version}</min-version>
   </conditions>
 
-  <packages>
-    <package>sonia.scm.mail</package>
-  </packages>
-
-  <resources>
-    <script>/sonia/scm/mail/sonia.mail.js</script>
-  </resources>

+  <resources>
+    <script>assets/scm-mail-plugin.bundle.js</script>
+  </resources>

 </plugin>

Java sources (src/main/java)

• try to compile the sources: mvn compile
• fix problems (TODO more help here)
• Remove XML accept headers from REST Resource classes -> SCMMv2 supports JSON only
• Migrate REST Resources (e.g. v2, add to Index Resource, Update Links) - See core plugins Git, Hg, Svn, e.g. GitConfigResource

UI (src/main/js, src/main/webapp)

• remove all SCM-Manager 1.x ui code from resource directory (src/main/resources)
• create package.json with the following content (replace name-of-plugin with the name of your plugin):

{
  "name": "@scm-manager/name-of-plugin",
  "license": "AGPL-3.0-only",
  "main": "src/main/js/index.tsx",
  "scripts": {
    "build": "ui-scripts plugin",
    "watch": "ui-scripts plugin-watch",
    "postinstall": "ui-plugins postinstall"
  },
  "dependencies": {
    "@scm-manager/ui-plugins": "2.0.0"
  }
}

• create a tsconfig.json with the following content:

{
  "extends": "@scm-manager/tsconfig",
  "include": [
    "./src/main/js"
  ]
}

• run mvn process-resources to install the required JavaScript libraries
• create new ui at src/main/js (for JavaScript code) and src/main/webapp (for static files) (TODO more help)
• Start SCM-Manager with the plugin using mvn run - features hot reloading of UI & Java Code.
  In order for Java classpath resources to be reloaded in IntelliJ, pressing compile is necessary.

Some more hints:

• For Configuration UIs use ConfigurationBinder
  • See core plugins Git, Hg, Svn, e.g. scm-git-plugin/index.ts .
    Note that readOnly property checks if update link is returned by REST resource
• Don't forget i18n for Plugins

Further reading

• UI Extensions - Extend the SCM-Manager UI
• scm-manager/ui-components - Reusable UI components within SCM-Manager
• smp-maven-plugin - Plugin that facilitates efficient plugin development for SCMM