Introduction

These are the instructions for developers looking to contribute or experiment with the source code for the Keysight Atlassian Plugins.

Setting up the Development Environment

Pre-requisites

• The Atlassian SDK
• IntelliJ Community or Ultimate Edition (recommendation)
• Clone the source code from Bitbucket

Top Level Directory and File Organization

At the top level are folders containing the plugins targeted to the various Atlassian applications (i.e. confluence, jira and bitbucket). Within each application folder are sub folders which are be intended to either contain a plugin, an instance of the Atlassian application or some arbitrary data. The general idea is to fire up a particular version of the Atlassian application in one of the container folders and do plugin work in one of the plugin folders. This makes it easier to switch between application versions.

Getting Started

Fire up an instance of the application

• Open a command prompt
• Move into the container folder such as .../confluence/6-2-0
• execute atlas-run

Build and load all plugins

• Open a second command prompt
• Move in to the container folder such as .../confluence/6-2-0
• execute atlas-package

Making Changes

Edit, build and reload a single plugin using the steps below * Make changes to the plugin * Move in to the plugin folder such as .../confluence/html-elements * execute atlas-package

Adding a New Application Container

• Open a command prompt
• Move in to the application folder such as .../confluence
• execute the appropriate create command such as atlas-create-confluence-plugin
• set the group to be com.keysight and the artifact to be the dash delimited version such as 6-2-2.
• copy the pom from a preexisting container, such as cp ./6-2-0/pom.xml ./6-2-2/pom.xml
• edit the ./6-2-2/pom.xml and change the references from 6-2-0 to 6-2-2 and 6.2.0 to 6.2.2
• execute atlas-run

You will need to insert the developer license, setup the smtp server and rebuild all of the Keysight plugins to get them to load into the new instance. This only needs to be done once for the container unless you execute atlas-clean where upon you will need to do it all over again.

Keysight Plugin Standards

Plugin Layout

The plugin is coded up in the transformerless paradigm. The Keysight plugins pull most of their dependencies from a parent pom.xml file, only using the plugin's pom.xml file to set the name, version and OSGi imports.

Java Namespaces/Directories

The java directories are broken up into several namespaces: macros, rest, events, helpers

• Code for macros is in .../src/main/java/com/keysight/<artifact-id>/macros
• Code for rest services is in .../src/main/java/com/keysight/<artifact-id>/rest
• Code for event listeners is in .../src/main/java/com/keysight/<artifact-id>/events
• Code for everything else is in .../src/main/java/com/keysight/<artifact-id>/helpers

Adding in new OSGi components

In the transformerless design, there is a requirement for at least one javascript file to annotate imported classes. This was centralized into .../src/main/java/com/keysight/<artifact-id>/helpers/ComponentImports.java. Therefore, when a new OSGi import is required, the ComponentImports.java file needs to be updated and the plugin's pom.xml file needs to include the package containing the new resource.

i18n, xml and velocity templates

• All of the i18n files are located in .../src/main/resources/com/keysight/<artifact-id>/i18n All of the vm template files are located in .../src/main/resources/com/keysight/<artifact-id>/templates All of the xml templates (for blueprints) are located in .../src/main/resources/com/keysight/<artifact-id>/xml

Macro Documentation

All of the macros use a self documentation paradigm. In this pattern there are four touch points:

• The link to the documentation is put in the i18n properties file
• The javascript executed by the link is in the .../src/main/resources/js/glossary.js file
• The javascript call is received by a Rest service (.../src/main/java/com/keysight/glossary/rest/RestServices.java )
• The Rest service pulls in the help content from a velocity template (.../src/main/resources/com/keysight/glossary/templates/<macro-name>-help.vm

Atlassian-plugin.xml Fragments

The plugins use the atlassian-plugin.xml fragments pattern which allows the file to be broken up in to multiple xml files. For the transformerless plugins, there is an entry in the plugin's pom.xml listing out the directories that are scanned for xml fragments. In case the plugins are ever migrated away from the transformerless pattern, the search paths are also duplicated in the main atlassian-plugin.xml file. All of the fragments are contained under the META-INF folder

GIT Workflow

This development follows Vincent Driessen's suggestion on a successful git development model Read more

Home