Contributor Setup

Setting Up Development Environment

Initial Setup

• Follow the first few steps in this tutorial to install and run the Atlassian Plugin SDK https://developer.atlassian.com/display/DOCS/Set+up+the+Atlassian+Plugin+SDK+and+Build+a+Project http://blogs.atlassian.com/2012/11/introducing-atlassian-plugin-sdk-4-1-the-ultimate-edition/
  • If you need an app installer... https://developer.atlassian.com/docs/getting-started/downloads
  • Verify installation with atlas-version and run atlas-mvn eclipse:eclipse
• If java not installed (Mac)
  • Install brew if not installed: https://developer.atlassian.com/docs/getting-started/set-up-the-atlassian-plugin-sdk-and-build-a-project/install-the-atlassian-sdk-on-a-linux-or-mac-system

brew update
brew cask install java

• If on a Mac (El Capitan or later) add the following to ~.bach_profile to create the $JAVA_HOME system variable. Test it with echo $JAVA_HOME in terminal.

export JAVA_HOME="$(/usr/libexec/java_home)"

Fork Project

• Fork repository each of the repositories in the table above from the http://github.com/constantcontact/voc-utilities-for-jira and clone your fork locally. Create a folder in your home directory to clone each of these projects into (e.g. ~./ctct_jira_utilities).
• If you want to pull from the github constantcontact repo and push to your fork, then edit your local repo's .git/config to have this for the [remote "origin"] section

url = git@github.roving.com:constantcontact/voc-utilities-for-jira.git
fetch = +refs/heads/*:refs/remotes/origin/*
pushurl = ssh://git@github.roving.com:your-user-name-here/voc-utilities-for-jira.git
push = refs/heads/*:refs/heads/*

• git checkout development (or whatever branch you're working on)
• If you'll be working in eclipse
  • Run atlas-mvn eclipse:eclipse from the project folder to prepare the project for the eclipse IDE
  • Import the repo's directory into eclipse as an existing maven project
  • If you have an existing apache maven installed on your machine with a conf/settings.xml file which points to Artifactory (e.g. for working on other CTCT projects like QE TAF), then place another apache maven with a default settings.xml file in a separate location and ensure your eclipse > Window > preferences and your maven build run configuration are set to use this other apache maven.

Running Jira Locally

• From the cloned project directory, run atlas-run to start a local instance http://localhost:2990/jira or http://_<yourhostname>_:2990/jira
• Log in as admin:admin
• Install Jira Agile from the "Agile" menu item (if no drop-down menu for Agile) by clicking "Agile" on the Jira menu bar. The installation will prompt you for Atlassian account information. Enter your http://my.atlassian.com credentials (create a new one from that site if you don't already have an account). This will generate and install a trial license to develop with.
  • This will add the Issue Types Bug, Improvement, and New Feature
• Add the Issue Type "Support Request" from http://localhost:2990/jira/secure/admin/ViewIssueTypes.jspa
• Create a Scrum project to test with (will include the Strum issue types and a Scrum workflow)
• To reload new code from within the JIRA instance (instead of packaging and uploading a new jar), open an new terminal window to the project location and run atlas-package. Jira "QuickReload" will detect the new jar and automatically update your running instance locally.
  • Note: The property enableQuickReload is set in pom.xml and supersedes FastDev and FastdevCli methods.
• Atlassian Wired Test Framework: https://developer.atlassian.com/display/DOCS/Run+Wired+Tests+with+the+Plugin+Test+Console
• Use Ctrl+D in the terminal window Jira is running from to gracefully shut down Jira (Ctrl+C if need to force down).
• When building the plugin, run atlas-clean, atlas-compile, atlas-package. This packages the lib jar classes inside the plugin.
  • Note: atlas-clean will reset your local JIRA instance's data.

Remote Debugging

• Launch local Jira in debug mode (JIRA 7.0.0 requires Tomcat v7)

atlas-debug --jvm-debug-port 5005 --jvm-debug-suspend -c tomcat7x

• This will pause once the transport dt_socket listening port 5005 is broadcast, so you can connect for remote debugging from your IDE
• In your IDE, run the Debug configuration "Remote Java Application" to listen on localhost port 5005 for your project name with a Standard (Socket Attached) connection type.
• Jira will continue to load
• Browse to Jira http://localhost:2990/jira or http://_<yourhostname>_:2990/jira

Generate saved data

Generating saved data in your local database that survives atlas-clean to seed your local database. https://developer.atlassian.com/docs/getting-started/writing-and-running-plugin-tests/create-test-data-and-a-test-fixture

• Create and use test data:
  • Run Jira from the project folder atlas-run (or see debug mode above) and create sample data baseline
  • Stop Jira Ctrl+D
  • Create zip file of the test data atlas-create-home-zip
  • Copy zip to test resource folder cp target/jira/generated-test-resources.zip src/test/resources
• Use this data in the pom.xml file

<configuration>
    <productVersion>${jira.version}</productVersion>
    <productDataVersion>${jira.version}</productDataVersion>					                                          
    <productDataPath>${basedir}/src/test/resources/generated-test-resources.zip</productDataPath>

Memcached

This plugin uses memcache for VOC Defect Chart gadget rendering (see http://memcached.org). This requires the spymemcached client and memcache server(s) to be reachable. There are also multiple web clients to configure and monitor your memcached server.

Memcached Server

• To run a local memcached server
  • install server brew install memcached
    • commands can be passed to homebrew memcached server in the configuration file "Program Arguments" array (Mac: ~/Library/LaunchAgents/homebrew.mxcl.memcached.plist, linux: /etc/memcached.conf).
  • if other than localhost, configure or pass in the server URL with the -l parameter
  • run server /usr/local/opt/memcached/bin/memcached (alternatively brew services start memcached to launch and restart at login)
  • ps ux | grep memcached to see what port memcached is running on
  • test server: connect telnet localhost 11211, status, quit
  • brew services stop memcached to stop
  • you can also run the server with a different port directly... /usr/local/opt/memcached/bin/memcached -p 11212
  • if you change the port (default port 11211), then specify this port in the VOC Volume administration console
  • if you run into cache memory errors, then you can increase the heap space with the -m parameter (default is 64)

Memcached Client

• Configure your memcached server URL and port address in the VOC Volume administration configuration page
• If runtime error "java.lang.ClassNotFoundException: net.spy.memcached.MemcachedClient" then atlas-clean and atlas-package to reload the client into the project jar.