If you are using scrum and agile within your organization, you already know about the daily stand-up meeting and the value its brings to the team. Many organisations who have not fully adopted scrum still find the stand-up meeting to be extremely useful when done properly.

Pyxis Technologies have just released a really neat iPhone/iPod Touch app - the _agilely Timer. The application allows you to efficiently facilitate daily stand ups, roundtable discussions and manage simple timeboxes. It costs $1.99 with all monies raised going to FIAN - FoodFirst Information and Action Network.
As Francois Beauregard said to me, "start standing-up for something important".

You can learn more about the _agilely Timer or even buy it direct from the App Store.

Sure, there are teams who are "more agile", there are teams who are less. Almost every team applies different agile practices. That's OK as we believe in self-organisation and bottom-up evolution. Still we all believe in the 4 fundamental principles of agile philosophy, which are compatible with our company values.

When Crucible became part of the Atlassian suite, a lot of us wondered how code review would match our agile environment. Two years later, code review has become an integral part of our agile developers' day-to-day jobs. Some say they are addicted to it. Let me tell you why.

I am not going to elaborate on an obvious advantage of code review: improved code quality. Instead, I would say that code quality is a nice side effect, but not the purpose of code review in our teams.

Code review is one tangible way that we enact the first principle of the Agile Manifesto: "Individuals and interactions over processes and tools". Here are some examples of how code review helps us collaborate better:

New team members

Atlassian is constantly growing. We hire passionate, often quite- experienced developers who need to dive into our non-trivial code base very quickly. In addition to new hires, existing team members sometimes rotate to different temporary or permanent positions.

Code review makes ramping up on a new code base faster and less painful, and helps maintain engineering knowledge across the team and the company over time. People more experienced in the code base review newbies' commits (there's no better way to learn the product than to start coding bugs or stories), and then advise them on which design inconsistencies they introduced and which shared components or utilities they should use and how. In return, the newbies can bring invaluable experience, good engineering practices, useful libraries, nice patterns, tricks, etc. from their former teams, resulting in fresh insights to improve the code base. In short, code review is a two-way conversation. Both the author and reviewers communicate and learn from each other.

Code review is even more important when a really junior developer joins a team. Senior developer don't have time to hand-hold the junior folks, since they need to be coding. That said, doing small but frequent code reviews of the junior developer's code is no big deal. The result? Senior developers can focus on writing code for most of the day and spend a 10-15 minutes a couple times per day to review the code changes by junior developers. The junior developers benefit from feedback, and the senior developers haven't lost valuable coding time.

Geographical distribution

Atlassian develops software on 3 continents, in time zones which differ by as much as 10 hours. Most teams working on a given code base are co-located (it really helps), but sometimes it's just not practical or feasible. Thus we ended up with a few geographically distributed teams - a big problem for some agile practices such as pair programming and daily stand ups.

Tools-supported code review comes to the rescue here by encouraging and facilitating knowledge flow between different locations.

With asynchronous code reviews, time zone differences can actually be an advantage. We often raise a review in the afternoon (as a good summary of our day's work), ask for review by colleagues across the ocean and go home. When we arrive at work the next morning, we have their review feedback: they were working on it while we were asleep! First thing in the day, we can answer questions and fix identified problems, and then proceed with our daily development tasks.

Integration

Code bases do not live in isolation. Most of Atlassian's products integrate with each other in some way or another.

For example, I work on IDE Connectors, which need to talk to Atlassian server products via remote APIs. These APIs are continuously evolving, often in response to the needs of the IDE Connector team. The server product teams are mostly located in Sydney, and their work day is ending just as ours is beginning.

Code review is the main way for the IDE Connector team to provide feedback about the remote APIs we rely on. Whenever there is a change related to a remote API, I am one of the reviewers - thus I can learn what is going on on the server side, constructively criticise the evolution of the API, and ensure that my teams interests are at least heard if not fulfilled.

A similar situation arises when you need to program something in the product you normally don't work on. I call it "guest programming" - e.g. you need to add some missing API or plugin point or just fix a problem which is only reproducible in your environment.

Code review enables guest programming by increasing courage of both sides. The team which owns the product is less reluctant to let an outside person touch their code base, and the guest programmer has more courage because other folks will review his code to prevent any nasty bugs.

Talking about courage - some of us actually feel anxious when deprived of code review. Unit tests establish a safety net which helps you be courageous to mercilessly refactor and improve the code while avoiding nasty regressions. Similarly, code review is another safety net, which gives you this feeling that your crazy ideas will be evaluated by others before they will go to production, and that your great design, utilities or tricks have a chance to be spotted and reused in other places by other team member. This is a real teamwork!

Code review may be difficult and costly to implement and sustain. Not every team or team member wants to do pair programming, and code review meetings can be too time-consuming. Obviously we use Crucible, which handles the logistics of a review and lets developers concentrate on the most valuable part of code review: thinking about the code and providing feedback.

In the next instalment I'll share a few pieces of advice and precautions related to implementing code review in an agile team or company as a standard process.

In the third and last instalment I would like to compare pair programming with code review and reveal a few rules around code review that evolved at Atlassian.

Have an opinion or question? Drop us a comment below!

But before we announce the winners, let's take a quick look at what the contestants were coding for. This years competition had prizes valued at over $54,000 USD up for grabs including $5,000 in cash, a MacBook Pro, an Amazon Kindle, free conference passes and a whole bunch of software from Atlassian and our generous sponsors.

This year, in addition to the Grand Prize, we've divided Codegeist into four categories.

• Best Cross-product Integration
• Best Theme
• Most elegant use of Javascript
• OpenSocial Gadget

Without further ado, here are the winners:

Category Winners

Best Cross-product Integration

Best Theme

Most elegant use of Javascript

Best OpenSocial Gadget

The Grand Prize

2nd Prize

1st Prize

• Making a field mandatory depending on other data entered in to the form
• Making a field read-only dependent on user role or group
• Doing server-side validation of field data, before the form is submitted
• Setting a field value dependent on other form data

Thanks

Plugin Developers

Sponsors

When I think of Agile, I tend to think of the awesomeness it can bring me as a performance engineer. I see short cycles where the code is usually always stable and features are delivered incrementally. I get to watch the performance of the system evolve over time. Unfortunately, this means I'm testing software all the time. Thats fine though - none of this is by hand - this kind of repetitive task is perfect for automation.

It's clear that automating testing is important - automated tests mean you have more time to do investigation while you make your build system do the repetitive tasks, and when your build system does the heavy lifting then it's easier to test more regularly. More regular testing means you find problems sooner and go home on time.

In this blog, I'm going to go over how to take your JMeter performance tests and put them into a Maven build which you can run on your continuous integration server as often as is needed. I'll introduce you to the Chronos Maven plugin which can control JMeter in a repeatable way and has reporting features which can be used to gain useful information about the performance test.

Prerequisites:

For this blog, you'll need the following prerequisites:

• A working knowledge of Maven
• Working JMeter Performance tests
• A Maven repository set up for retrieving artifacts and deploying new ones.

Atlassian has a well maintained Maven infrastructure - if you're just getting started, I'd suggest you read Sherali Karimov's great guide on setting up Maven infrastructure here.

The JMeter tests used in this paper are fairly complete, however this is not necessary for your first pass at getting the automation running. Its more important to get started and then improve what you have as your need more features.

When you are writing your JMeter tests, I would suggest keeping the information about the data you're going to be testing separate from the testing logic. By this, I mean keep the "flow" of your test in JMeter but use CSV files to define what URLs or options need to be used when testing. For example, instead of hardcoding a list of pages to sample rather put this into the CSV and load that into JMeter using the "CSV Dataset" controller. This way, you can change the CSV files to test a different set of pages or data in your application.

Here are the main steps I'm going to cover:

1. Create a performance test Maven artefact
   1. Write a Maven pom.xml for the performance tests
   2. Package & deploy the tests to the Maven repository
2. Write a Maven pom.xml to run the performance tests against an application
3. Run the tests
4. Automate the tests with Bamboo

George Barnett discusses performance testing inside Atlassian

Create a performance test artefact

In order to use your performance tests in an automated environment, you need to get them into Maven. Below are the components for a sample artefact, starting with the directory structure to use.

./pom.xml
./src
./src/main
./src/main/assembly
./src/main/jmeter
./src/main/resources

There are 3 directories in the src/main tree:

In this test artefact, the CSV resource files which are distributed should contain the bare minimum information needed to run the test - the actual data you will use will be stored in another project. If your application has a demonstration dataset then it would be good to add information about this data to the CSV files as an example.  Don't leave the files blank - it makes it easier for others if you have a simple structure inside as an example.

$ cat pagePaths.csv
/path/to/page.html

Write a pom.xml for the JMeter tests

Resource: pfe-perftest-pom.xml

To deploy this project using Maven you'll need to write the pom.xml. I've attached a sample pom.xml to this post but here's some of the things you need to take care of:

Parent Pom:

<parent>
  <groupId>com.atlassian.pom</groupId>
  <artifactId>atlassian-public-pom</artifactId>
  <version>14</version>
</parent>

Atlassian's performance tests are public. For this reason, I include the Atlassian Public pom as a parent. This ensures that this project inherits the correct settings and will be deployed to the correct place.

Artifact Id and Version:

<groupId>com.atlassian.performance.fisheye</groupId>
<artifactId>performance-test</artifactId>
<packaging>pom</packaging>
<name>FishEye Performance Tests</name>
<version>2.0-SNAPSHOT</version>

To keep things easy, set the version of the pom to the same as whatever software you're testing. When the software you're testing releases, bump the version to follow them (don't forget to tag the previous release!).

The build section of the pom.xml has two plugins:

Resource: pfe-public-distribution.xml

1. Maven assembly plugin.  This uses the public-distribution.xml configuration file to package the tests and the sample dataset into a .zip and .tar.gz archive.  It specifies which files and directories should be included into the generated archive.
2. Maven clean plugin. This plugin is set up to remove any .jtl files from the results directory to prevent leaking any test results into the archive file. .jtl is the extension given to output files that Listeners save result data in during the JMeter test run.

Packaging the JMeter test

If everything is in place you should now be able to use Maven to package and deploy the JMeter tests to your Maven repository. This is the first step to being able to include them in a repeatable test.

First, check that the artefact generated is correct:

spoem:trunk gbarnett$ mvn verify
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building Performance Tests
[INFO]    task-segment: [verify]
[INFO] ------------------------------------------------------------------------
[INFO] [site:attach-descriptor]
[INFO] [assembly:attached {execution: public}]
[INFO] Reading assembly descriptor: /Users/gbarnett/fisheye/performance-test/trunk/src/main/assembly/public-distribution.xml
[INFO] Building zip: /Users/gbarnett/fisheye/performance-test/trunk/target/performance-test-2.0-SNAPSHOT.zip
[INFO] Building tar : /Users/gbarnett/fisheye/performance-test/trunk/target/performance-test-2.0-SNAPSHOT.tar.gz
...

Check the resulting ZIP files to ensure that they're packaged correctly.  Check that all the files you need are there.  For an example of what a working artefact looks like, have a look at the FishEye performance test artefacts here 

Once you're happy with this, you can deploy to the remote repository.

spoem:trunk gbarnett$ mvn deploy
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building Performance Tests
[INFO]    task-segment: [deploy]
[INFO] ------------------------------------------------------------------------
[INFO] [site:attach-descriptor]
[INFO] [assembly:attached {execution: public}]
[INFO] Reading assembly descriptor: /Users/gbarnett/fisheye/performance-test/trunk/src/main/assembly/public-distribution.xml
[INFO] Building zip: /Users/gbarnett/fisheye/performance-test/trunk/target/performance-test-2.0-SNAPSHOT.zip
[INFO] Building tar : /Users/gbarnett/fisheye/performance-test/trunk/target/performance-test-2.0-SNAPSHOT.tar.gz
[INFO] [install:install]
..
[INFO] [deploy:deploy]
..
[INFO] Retrieving previous build number from atlassian-m2-snapshot-repository
Uploading: https://maven.atlassian.com/public-snapshot/com/atlassian/performance/fisheye/performance-test/2.0-SNAPSHOT/performance-test-2.0-20080929.031627-1.zip
[INFO] Retrieving previous build number from atlassian-m2-snapshot-repository
Uploading: https://maven.atlassian.com/public-snapshot/com/atlassian/performance/fisheye/performance-test/2.0-SNAPSHOT/performance-test-2.0-20080929.031627-1.tar.gz
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 41 seconds
[INFO] Final Memory: 14M/762M
[INFO] ------------------------------------------------------------------------

If you see this it means you have successfully deployed your JMeter tests to your Maven repository. If you find that Maven has failed then go over the setup carefully to check everything is in place. If you require more debugging information from Maven, you can run the above commands with the -X switch to enable more logging.

Once the build is successful and your artefacts are deployed to your Maven repository, they can then be included in your automated performance test.  In the next part, I'll create project which will run the performance tests against your application.  This Maven build can then be automated.

Directory structure for the automated test

The structure for the automated test is slightly different as you can see below.  Create a new project in your SCM and create the directories listed.

The main difference is that we're using the test directory instead of main. This is because the main purpose of this project is to run tests instead of build an artefact.

./pom.xml
./src
./src/test
./src/test/resources
./src/test/resources/jprofilerconfig.xml
./src/test/resources/dataset-sanity1
./src/test/resources/dataset-sanity1/config.xml
./src/test/resources/dataset-sanity1/repository
./src/test/resources/dataset-sanity1/repository/filePaths.csv
./src/test/resources/dataset-sanity1/repository/repoNames.csv
./src/test/resources/dataset-sanity1/repository/repoPaths.csv
./src/test/resources/dataset-sanity1/search
./src/test/resources/dataset-sanity1/search/complexTerms.csv
./src/test/resources/dataset-sanity1/search/eyeqlTerms.csv
./src/test/resources/dataset-sanity1/search/simpleTerms.csv

Write a pom.xml for the automated test

Resource: pfe-automation-pom.xml

It's best to start out by working out what actions (and in which order) you will need to take to test your application. In this example, here are the steps the test will perform:

1. Prepare the FishEye data directory using the chosen data to load
2. Prepare the Jprofiler config
3. Download and extract the FishEye application
4. Start FishEye
5. Run a JMeter test using the defined CSV data
6. Stop FishEye
7. Run reporting on the JMeter outputs and generate a site directory for upload

It's important to define what order this work should occur in before starting so you know what you are aiming for.  I'm not going to annotate the whole pom.xml since it is several hundred lines long.  I'll go over the important parts which you may not have seen before - I would suggest opening a copy locally before proceeding.

POM: Define build profiles

There will be many tasks to perform and settings to choose when running the test. Some of these tasks will need to happen every time (for example, setting up a database) and others will only need to happen when you are testing something specific (such as adding a code profiler). Maven provides the concept of Profiles (not to be confused with code profiling) which can be used to add and remove plugins to your test harness.

In this example, I will set up two profiles. By default, the information contained in them will not be used but when we do want to use it, it can be added to the test with a simple switch.

POM: Import Dependencies

<dependency>
  <groupId>com.atlassian.performance.fisheye</groupId>
  <artifactId>performance-test</artifactId>
  <type>zip</type>
  <version>${project.version}</version>
</dependency>

The JMeter performance test artefact we packaged up earlier is a dependency in this test. Using the maven-dependency-plugin this artefact will be extracted into the target/test-classes/ directory for use.

The maven-dependency-plugin is also used to download and extract the application that's going to be tested.

The Maven exec plugin is used to start FishEye using the exec:exec goal. FishEye is started at the pre-integration-test phase so it's ready for use with the JMeter goals which run at integration-test phase.  If your application runs inside an application server such as Tomcat or Jetty, you should use the Maven Cargo plugin to start and stop your application.

POM: Plugins - JMeter configuration

The JMeter test is run by the Maven Chronos plugin which is responsible for running JMeter. There a few settings which you need to pay attention to:

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>chronos-maven-plugin</artifactId>
  <version>1.0</version>
  <configuration>
    <jmeterhome>${jmeter.home}</jmeterhome>
    <historydir>${history.directory}</historydir>
    <heap>756m</heap>

jmeterhome

Where JMeter is installed but the base directory - JMeter should be in bin/jmeter under this directory. It's worth nothing that the plugin does not start jmeter via the startup script but rather invokes the jar's directly.

historydir

This variable should be a unique directory for the build. Since you're going to eventually have several profiles with different datasets and JVM versions, it should take this into account. I use the following format:

history.directory / product / product.version-java.version-data.version

heap

It's important to give JMeter enough memory. This is especially true if your test uses multiple Listeners. As you will see later when I cover reporting, the default report will include a graph showing Garbage Collection. This graph is actually JMeters garbage collection, but it's good to keep an eye on it. If JMeter spends too much time doing GC then the test results will be skewed and useless.

The settings in the attached pom.xml include some tweaks to the Garbage Collection, new size and survivor ratio.

POM: Plugins - JMeter System Properties

These variables are initially set as global configuration items but are then overridden in the profile for the dataset used.  The variables here will be passed to JMeter using the -Dvariable.name=value command line switch.

<sysproperties>
  <property>
    <name>script.runtime</name>
    <value>${script.fixedload.runtime}</value>
  </property>
  <property>
    <name>script.base</name>
    <value>${project.build.directory}/performanceTest</value>
  </property>
  <property>
    <name>resource.dir</name>
    <value>${dataset.location}</value>
  </property>
</sysproperties>

JMeter accepts external variable input using the P function, eg: ${__P(script.runtime,1800)}

Using sysproperties in the pom, it's possible to override the variables inside the JMeter test. The most useful reason for this doing is to change the location of the resources which contains the CSV files which define which pages to sample directory. In the above example, the dataset.location variable is modified by the chosen profile in the pom and this is passed to JMeter, thus allowing the override of the resource directory used for testing.

POM: Plugins - JMeter test executions

<executions>
  <execution>
  <id>71_fixedload-test</id>
    <configuration>
      <dataid>fixedloadtest</dataid>
       <input>${project.build.directory}/performanceTest/jmeter-test-fixedload.jmx</input>
    </configuration>
    <goals>
      <goal>jmeter</goal>
      <goal>check</goal>
      <goal>savehistory</goal>
    </goals>
  </execution>
</executions>

The sysproperties shown earlier will be applied to all exections of the plugin. There are however two config variables above must be unique for each execution however:

dataid

This provides a unique name the test data output will be known as. It will be used to save files in the reports later and the savehistory goal will use this to save the data for this execution.

input

This is the .jmx performance test script to run. 

Chronos Build Goals

POM: Reporting

<reporting>
  <plugins>
    <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>chronos-maven-plugin</artifactId>
      <version>1.0-atlassian-1</version>
      <configuration>
        <historydir>${history.directory}</historydir>
      </configuration>
      <reportSets>
        <reportSet>
          <id>fixedloadreport</id>
          <configuration>
            <dataid>fixedloadtest</dataid>
            <reportid>jmeter-fixedload-report</reportid>
            <title>JMeter Fixed Load Test Report</title>
            <description>
              <![CDATA[Fixed Load Test Report]]>
            </description>
          </configuration>
          <reports>
            <report>report</report>
            <report>historyreport</report>
          </reports>
        </reportSet>
      </reportSets>
    </plugin>
  </plugins>
</reporting>

The reporting lifecycle produces graphs, one of which I've shown as an example at the top of the page. You should include one reportSet for each execution that was defined in the build part of the Chronos plugin. The dataid of the reportSet should match the relevant test execution dataid.

POM: Profiles

In order to control the dataset, I've added a profile for each piece of data I will be loading into FishEye. At the moment, I have only one, but making another will be easy with profiles. Most of the profile will be setting up variables which will be used elsewhere in the pom. For example, the dataset.location variable will be passed into JMeter using a sysproperty to set the resource base directory.

<profile>
  <id>dataset-sanity1</id>
  <properties>
    <repository.zipfile>${performance.datadir}/sanity1.zip</repository.zipfile>
    <repository.location>${repository.basedir}/sanity1</repository.location>
    <dataset.location>${dataset.basedir}/dataset-sanity1</dataset.location>
    <dataset.version>sanity1</dataset.version>
    <fisheye.config>${dataset.location}/config.xml</fisheye.config>
  </properties>
</profile>

Run the Tests!

Once your pom is complete, you can run the test using the mvn command. Don't forget to have any profiles you need as part of the command:

$ mvn verify site -P dataset-sanity1
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building FishEye Performance Test Runner
[INFO]    task-segment: [clean, site]
[INFO] ------------------------------------------------------------------------
[INFO] Preparing chronos:report
[INFO] [dependency:unpack {execution: 30_unpack-fisheye-zip}]..
[INFO] [exec:exec {execution: 60_start-fisheye}]
..
[INFO] [chronos:jmeter {execution: 71_fixedload-test}]
[INFO] Excuting test /Users/gbarnett/fisheye/automated-perftest/trunk/target/performanceTest/jmeter-test-fixedload.jmx
[INFO] Created the tree successfully using /Users/gbarnett/fisheye/automated-perftest/trunk/target/performanceTest/jmeter-test-fixedload.jmx
[INFO] Starting the test @ Fri Oct 03 12:32:53 EST 2008 (1223001173145)
[INFO] Display Summary Results During Run +   783 in 184.3s =    4.2/s Avg:    22 Min:     1 Max:  1377 Err:     0 (0.00%)
[INFO] Display Summary Results During Run +  2616 in 180.0s =   14.5/s Avg:    23 Min:     1 Max:   565 Err:     0 (0.00%)
..
[INFO] Display Summary Results During Run +   448 in  25.6s =   17.5/s Avg:    41 Min:     1 Max:   861 Err:     0 (0.00%)
[INFO] Display Summary Results During Run = 29095 in 1829.9s =   15.9/s Avg:    29 Min:     1 Max:  1377 Err:     0 (0.00%)
[INFO] Tidying up ...    @ Fri Oct 03 13:03:25 EST 2008 (1223003005682)
[INFO] ... end of run
..
[INFO] [exec:exec {execution: 85_stop-fisheye}]
[INFO] [chronos:savehistory {execution: 71_fixedload-test}]
[INFO] [chronos:check {execution: 71_fixedload-test}]
..
[INFO] Generating "jmeter-fixedload-report" report.
[INFO]   tests: 10
[INFO]   jmeter samples: 29095
[INFO]  generating charts.....
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 31 minutes 39 seconds
[INFO] Finished at: Fri Oct 03 13:04:01 EST 2008
[INFO] Final Memory: 55M/746M
[INFO] ------------------------------------------------------------------------

The test has now run successfully. In the target directory you'll find a site directory which contains HTML and images to make up a build report. This will be uploaded to the URL specified in the distributionManagement section of the pom.

Automate the tests using Bamboo

Bamboo is a continuous integration server made by Atlassian and is perfect for running the tests regularly.

For information on creating a new build plan in Bamboo, see the document Creating a build plan in the online documentation for Bamboo.

In closing..

With this information, you can start to make a real difference to your development cycle. You'll find performance regressions faster and be on you way to code bliss. If you're interested in some of the processes which you can use to better integrate this cycle, see Andrew Prentice's blog on improving the QA cycle in You don't have to be Agile to be agile.

Learn more about software testing in an agile development environment

Actioning issues from commit messages is a feature that has been available in JIRA Studio for around a year. The documentation on how to use it (once it's set up) can be found here. This feature was, from the start, written as a feature that could be used outside JIRA Studio. However, there was a small amount of effort required to get it to that point. That effort has never been done, until now. Well, some of it has been done. It's still only recommended to be tried by only the bravest of dragon slayers.

First, a bit about how actioning issues with commit commands work. Atlassian has a little known cross product plugin called the Atlassian Notifier. This plugin implements WebHooks for Atlassian products. Using a REST interface, other servers can subscribe to notifications of events on the Atlassian product. In our case, a servlet in the JIRA FishEye plugin will subscribe to commit notifications from FishEye, this servlet will parse the commit messages, and action JIRA issues accordingly.

Requirements

In order to complete this task, you will need:

• To have completed the Atlassian Dragon Quest
• Version 3.1-beta1 of the JIRA FishEye plugin, available here
• A patch for the built in JIRA workflow
• The FishEye Atlassian Notifier plugin version 2.1-beta1, available here
• A Subversion repository that you can commit to (can be a local filesystem repository)
• The Firefox Poster plugin

Setup

1. Install the JIRA FishEye plugin 3.1-beta1 into the plugins/installed-plugins directory in the JIRA home directory
2. From the atlassian-jira directory, apply the workflow patch, using the command patch -p0 < jira-workflow.xml.patch
3. Restart JIRA
4. Install the FishEye Atlassian Notifier Plugin into the var/plugins/user directory in FishEye
5. Restart FishEye
6. Add your Subversion repository to FishEye.
7. Grant the "charlie" user you created administrator access to FishEye. This can be done by clicking the Administrators link in the FishEye administration menu.
8. In Firefox, log in to FishEye with the charlie user. Now, using the Firefox Poster plugin, send a POST request to {your fisheye base url}/plugins/servlet/notifier/{your repository}/COMMIT, with content type application/x-www-form-urlencoded, and the content url={your jira base url}/plugins/servlet/commitnotification&authenticationType=TRUSTED_APPS&username=charlie. The response code should be 201 Created.

You're now ready to go.

Testing

1. Create an issue in JIRA
2. Check out your source code. If using a file system SVN repository, make sure you specify the --username charlie option.
3. Make a change, and then commit, with a commit message of {ISSUEKEY} #resolve It works

Within a couple of minutes, your issue should be resolved, and a comment "It works" added to the issue.

If these instructions don't work for you (remember, this task was not for the faint hearted!), then please leave your feedback as comments on this post.

So, we've decided to extend the deadline for Codegeist until Sunday night, October 18th. That's just a few days before AtlasCamp, where were are going to announce the winners. (If you haven't booked your ticket to AtlasCamp, now is the time!)

Ending on October 18th means that we're going to have to work extra-hard to get the judging done. But it also means that we can give you all two extra weekends to polish your entries. I figured, if you are willing to you pull a few more all-nighters coding, then we can do the same with the judging.

So good luck, everyone and go get your entries in!

We've already seen the first few entries go up on the Entries page. I just wanted to take a second to encourage everyone to get your entries posted as soon as you can. I know that there's a rather overwhelming bias toward procrastination here, but let me urge you to try to overcome that tendency. As I said last year:

The plugins that were submitted early had the benefit of a month of real-world use, feedback, and bug reports. In general, those plugins ended up being substantially more polished and complete than those which appeared at the end. The authors were able to develop detailed documentation and to fix parts which didn't make sense. They put up lots of screenshots. But most importantly, they were able to fix bugs and add features that people requested.

So, my advice is release early, release often. As soon as you have anything workable, put it out and solicit opinions (the forums are a great place for this). The concrete feedback you gain on your Codegeist plugin will be more valuable than the element of surprise that you give up.

A little bit of real-world, real-user testing is critical: having a few people (besides yourself) try to install and use a new plugin will go a long toward making sure it also works when the judges try it. So, take advantage of the time left, and get your public out in the open as soon as possible!

Good luck!

Why Scala?

Scala is currently gaining a lot of traction in the Java community, for a number of reasons. Twitter replaced it's Ruby-based messaging backbone with one written in Scala. It also has a lot going for it as a language, and also compiles to bytecode just as Java does (Martin Odersky wrote both the Scala compiler and the current javac reference compiler).

What does this language have over Java?

There's a lot, and some of it certainly looks fairly strange compared to Java. Examples of some of the extras:

Methods as first-class objects:

//won't actually compile due to type constraints, but illustrates the point..
def run(method, param) = { method(param) }
run(System.out.println, "text")

Closures (of course! And lambda expressions here...):

var total = 0
List(1,2,3).foreach { x => total += x }

Static Typing:

No groovy-style fail-at-runtime typing. Everything here is statically typed and checked at compile time. Difference is that things are inferred, otherwise you need to declare the type:

var thing = 1
var other : Any = 1
thing = "new" //fail, was inferred as an integer
other = "new" //ok, marked as anything (value or ref type)

Traits:

Think interfaces with some code. And yes you can inherit multiple of them. So you effectively get mixins, or sort-of simple multiple inheritance.

There are a lot more; some more simple ones which I've missed from C# are Properties and more sensible super-constructor calling (class myClass(i : Int) extends mySuper(i){...}), but I won't go into the rest here. The language supports both OO and functional styles, so at the cost of complexity keeps both camps happy. There is plenty of scope for many Scala posts, and I'll probably do a Friday presentation on it soon, so I'll keep this post primarily concerned with how to write plugins in Scala. If you want more information on the language itself, check out the main Scala site.

How do you create a plugin with this?

Build

To build Scala code you can use a Maven2 plugin, and put code in src/main/scala & src/test/scala:

<plugin>
    <groupId>org.scala-tools</groupId>
    <artifactId>maven-scala-plugin</artifactId>
    <executions>
        <execution>
            <id>scala-compile-first</id>
            <phase>process-resources</phase>
            <goals>
                <goal>add-source</goal>
                <goal>compile</goal>
            </goals>
        </execution>
        <execution>
            <id>scala-test-compile</id>
            <phase>process-test-resources</phase>
            <goals>
                <goal>testCompile</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Or you can use your IDE. Idea 9 has a Scala plugin which is fairly good, it supports syntax highlighting, a few basic refactorings and some debugging. I believe Eclipse also has some Scala support.

Deploy

To run a Scala plugin in a standard Java app you simply need to add the runtime jar org.scala-lang:scala-library. Other than that you should be fine, and the code should just work. The main issues you are likely to have are with containers...

Problems

Velocity & WebWork

Yes, you don't really have to use Velocity, but when writing a Confluence plugin it's pretty tempting. Velocity will work with Scala, but you need to be aware of some things. Here is an example action:

class ScalaAction extends ConfluenceActionSupport {
 
 @scala.reflect.BeanProperty
 var myNumber : int = 21
 
 @scala.reflect.BeanProperty
 var myString : String = "testString"
 
 def execute = {
  try {
   myString = //do something
  } catch {
   case e: Exception => myString = "error!"
  }
  
  Action.SUCCESS
 }
}

The main thing to notice here is the @scala.reflect.BeanProperty annotations. This means that Scala will generate standard getters and setters for these properties, which can then be used by Velocity and WebWork as if you were using Java. Without using this annotation (and if you do), Scala will generate a getter/setter pair as propertyName() / propertyName_eq$(...) instead of getPropertyName() / setPropertyName(...). (Note that you can also annotate the whole class with @scala.reflect.BeanInfo to create getters/setters on every property.) I suppose you could still call the Scala getter with $action.myProperty(), but you'd lose WebWork injecting the properties.

Spring

Spring has identical issues to those above - i.e. using setter injection (mandatory for Confluence plugins-1 plugins) need getters and setters. There are however a few options other than using the above annotations. You could use a FactoryBean - although this also causes issues in plugins-1, top level beans are simply created and used, if you want some Spring magic, then it'll need to be a nested bean definition. I hoped that Spring would easily let me redefine the methods which it used to get and set bean properties, however it uses the standard Java Introspector to find these methods. Apparently this is being rewritten in Spring 3.0 (I haven't yet tried it) to allow using custom methods, so general Scala support could be added fairly simply with this. Note however that many Scala zealots are not a fan of using a DI framework as Scala is flexible enough to do this itself (like Groovy I suppose), and they often recommend the Cake Pattern instead.

If you're interested in Scala and want to exchange ideas with other plugin developers, come join us at Atlascamp!

Check out what the developers that attended last year are saying.

Matt Doar gave the event a great shout-out on his blog. One of Matt's reasons for attending again this year:

Plenty of opportunities to tell the core Atlassian developers and top management exactly what you think of their products

Chris Kohlhardt from Gliffy is having his whole development team attend this year. Chris just posted a blog that explains why you want to join them.

It's fun! In addition to learning about the Atlassian plugin ecosystem, we played games, drank beer, and generally had a good time. This isn't some giant conference where nobody knows your name.... since the event is limited to less than 100 people you'll definitely get to meet most of the central figures in the Atlassian development ecosystem.

Hope to see you there!

The Deets:
Date: October 21 - October 23
Location: The Oceano Hotel and Spa in Half Moon Bay
URL: www.atlassian.com/atlascamp

As Ross says:

AtlasCamp isn’t a boring junket where you sit through endless PowerPoint presentations, it’s fast paced and hands on with lots of coding and technical sessions.

I was fortunate enough to attend last year’s AtlasCamp, and I found it to be a fantastic experience. It was enlightening to hear from some of the top plugin developers in person about their thoughts and ideas for how they can make Atlassian’s already great products even better.

AtlasCamp is the best place to learn about the newest technologies percolating through the Atlassian ecosystem. We don't sit still, and there are a ton of new tools for you to use in extending and enhancing your Atlassian products. Ross agrees:

One of the main reasons that I’ve been developing plugins over the last couple of years is that it allows me to explore technology sets that otherwise I might not get to play with. Being able to run ideas past both Atlassian and other plugin developers is a great way for me to get valuable advice and feedback. Personally, I’m really looking forward to hearing about how I can develop plugins using Gadgets! Plus I’ll get to hear how I did in this year’s Codegeist competition.

I found the event to be a great way to talk to the other Atlassians/plugin developers in person. A lot of the communication I’ve had with people has been over email or IM, and it’s always nice to talk face to face! There was a great sense of camaraderie from everyone there, and I’m really looking forward to seeing both old and new faces and hopefully learning a thing or two!

AtlasCamp starts on October 21st in beautiful Half Moon Bay, CA. It's $200 registration for the conference, but it's an experience worth many times that. There will be over 20 Atlassian developers there (including Mike and Scott, Atlassian's co-founders), and we're all excited to hang out with you and listen your feedback. So sign up today!

Based on what we have already, I wrote a special JUnit test case and a runner for it. The runner executes all the JsUnit tests and reports the passing and failure as a JUnit4 test case.

One test for all (Js tests)

The test case uses its own runner and it only has one test function:

@RunWith(RhinoJsUnitRunner.class)
public class RhinoJsUnitTest
{
 @Test
 public void JsUnitTriggerTest() throws IOException
 {
  final String path = System.getProperty("jsunit.entrypoint");
  runJsUnitInRhino(path);
 }
}

Calling Rhino

In the runJsUnitInRhino() function, I created a separate process to run Rhino, because Rhino keeps calling System.exit() which terminates the build process. And the benefit of having a separate process is that I can collect the test result in Rhino's standard output stream. The test result looks like this:

Running com.atlassian.gadgets.test.RhinoJsUnitTest
INFO:        [Tue Sep 15 2009 16:15:40 GMT-0700 (PDT)] {ENVJS} adding value to history: file:/Users/scai/Code/AG-svn/trunk/dashboard-plugin/src/test/resources/index.html
INFO:        [Tue Sep 15 2009 16:15:40 GMT-0700 (PDT)] {ENVJS} Sucessfully loaded document at file:/Users/scai/Code/AG-svn/trunk/dashboard-plugin/src/test/resources/index.html
Loading tests.
TestRunner (6 test cases available)
> Starting test suite "AllTests"
=> Starting test suite "ParamTest"
-- Running test 1: "ParamTest.testStandardMessage"
-- Running test 2: "ParamTest.testMessageWithParameters"
<= Completed test suite "ParamTest"
=> Starting test suite "CookieTest"
-- Running test 3: "CookieTest.testEraseDefinedCookieSucceed"
-- Running test 4: "CookieTest.testValueSaveReadSucceed"
-- Running test 5: "CookieTest.testChangeSavedValueSucceed"
-- Running test 6: "CookieTest.testValueReadUndefinedCookieGetDefaultValue"
<= Completed test suite "CookieTest"
< Completed test suite "AllTests"
6 tests successful in 0.024 seconds.

Having these information, I can write a simple line parser to retrieve per-test result. Then the next step is to post the pass/fail event to JUnit and they will all be collected by Surefire.

Reporting to JUnit

In order to get the Notifier reference, I override the general JUnit4 runner:

public static class RhinoJsUnitRunner extends BlockJUnit4ClassRunner
{
 public RhinoJsUnitRunner(java.lang.Class<?> klass) throws InitializationError
 {
  super(klass);
 }
 
 @Override
 public void run(RunNotifier notifier)
 {
  runNotifier = notifier;
  super.run(notifier);
 }
}

The new runner intercepts the {{run}} method and saves the notifier reference, so that we could do the following event forwarding:

private static void pass()
{
 if(currentTest != null)
 {
  runNotifier.fireTestFinished(currentTest);
  currentTest = null;
 }
}

private static void fail(String details)
{
 Failure failure = new Failure(currentTest, new RuntimeException(details));
 runNotifier.fireTestFailure(failure);
}

That's all we need to run JsUnit tests as normal JUnit4 tests.

SystemProperty in Maven

There is one tricky part in starting the Rhino Shell. Rhino Shell evaluates scripts either from a given file path or from the standard input. We have to use the file path, because our "test.js" is only an entry point. It loads in more Javascript files using eval() method. Using standard input will require merging all the required Javascript into one big file.

In order to tell JUnit where to find our entry point, I had to explicitly configure the Surefire plugin in the pom.xml to store the path onto system properties.

<plugin>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <systemProperties>
            <property>
                <name>jsunit.entrypoint</name>
                <value>${basedir}/src/test/javascript/test.js</value>
            </property>
        </systemProperties>
        <junitArtifactName>junit:junit-dep</junitArtifactName>
    </configuration>
</plugin>

I tried setting the value inside the Maven Properties subtree, but the value was not passed to JUnit. It's only available to references within the pom.xml.

Now, the JsUnit tests are running like normal JUnit4 tests.

Getting Started

To get started take a look at our documentation and the "Styling Confluence Tabs" tutorial.

For the impatient, here is how to get your CSS into Confluence:

1. Log in as the Space Administrator.
2. Open the Space Admin page.
3. Click 'Stylesheet'.
4. Click 'Edit' to change the code in the text field.
5. Paste your custom CSS into the text field. (Once the text is saved here, you can make adjustments to it inline.)
6. Click 'Save'. The new CSS will be visible on all content pages in the space.

Part III: Technical Writing Insurgency (Part I | Part II)

"Reading the JIRA"

The Atlassian Technical Writers aren't clairvoyants, neither can we use The Force, but those would be really handy abilities in the documentation profession. The next best thing to supernatural powers of prediction is a technique we call "Reading the JIRA". Similar to reading the future in tea leaves, Tarot cards or the creases in your palm, reading the JIRA gives you a sense of things to come and critically, how plans and tasks are changing in the present time. Let me tell you, in an Agile project they'll be twisting and contorting like some mythical serpent in an old, violent legend.

We basically read every change that's going on in Atlassian's issue-tracking program, JIRA. As our own software developers are using JIRA itself to track their work which we are in turn documenting, by reading all of this JIRA material we have a powerful "early-warning" in place, that sometimes makes our prescience seem a little spooky. Milliseconds after a developer updates a spec in JIRA, we're immediately on the instant messenger, asking "How will this affect the documentation?". Sometimes they're a little shocked, responding with "Whoa! Easy there!". This may sound extreme, or perilously close to obsessive behaviour. Still, we've persistently found that by tracking the information flow continuously, monitoring changes Jedi style, we win critical days, hours and minutes that we then have up our sleeves to finish the job in time, no matter what's happened. The flip side of our obsession is that usually, none of the software developers would have thought to inform us about some critical change that turns our priorities upside down. They're bumbling along, hacking away in their IDE, humming blithely to themselves as the crisis bears down over days and weeks. Rather than a scheduled disaster, "Abracadabra"! We've magically got time to finish our work for the release.

At times, reading the JIRA is a lot like tapping the stream-of-consciousness from a high-school programming class packed with testosterone-fuelled egomaniacs, but that's the territory you step into when trying to probe the minds of Top-Gun software developers. Atlassian is most definitely full of those. It's competitive, intellectually vibrant and subject to tidal forces of opinion.

Authoring in Confluence

Another reason we are able to cope with the dynamic documentation work at Atlassian is due to our product, Confluence (which we also dogfood). Confluence is a Wiki, basically like a web server with pages that anyone can edit. For a Technical Writer, where our communication goal is purely informative, Confluence is a powerful solution. With established pages that we've released to the public, we can learn about a problem, find the page, edit the content, have it reviewed and re-publish it to the world in a small number of quick steps. We can have urgent maintenance work on the documentation completed in seconds, when all the pieces fall into place. With the inherent fast-editing capability in Confluence allowing anyone in the company to edit the pages, my subject matter experts are brought much closer to the content. It only takes a few minutes of their time and they can make all necessary changes immediately. This adds obvious bonuses to technical accuracy and speed of review (enabling multiple, iterative reviews to take place). Of course, professional writers are still essential to bring refinement, structure and enterprise standards of communication to the material.

If you're a Technical Writer about to embark upon an Agile adventure, you're in for an exciting ride. Throw out the rulebook, publish in a Wiki and get your developers using a quality issue tracker.

Finally, I will leave you with the words of Governor Bibble. Remember: "A disruption in communications can mean only one thing... invasion!"

Ed Dawson is the Technical Writing Team Leader at Atlassian.

This is the final installment in a three part agile technical writing blog series: Agile Technical Writing - Part I | Agile Technical Writing - Part II

Sarah Maddox discusses technical writing in an agile environment



Learn more about technical writing and agile development inside Atlassian

For the last 3-4 weeks the JIRA team has been following a development process where we are allowed to check in...when the build is broken.

Heresy...lunacy...insanity...

Well it turns out that it helps keep the build green.

And here is why...build latency.

I am defining build latency as the time from checking-in a change, finding out your broke the build and then checking in another change and knowing that you have fixed the build.

4 Months Ago

About 4 months ago our development process rule was that you must not check when the build is broken and you must not check in and go home unless you know it has passed.

Our unit tests and web functional tests were taken about 7 minutes and 2 1/2 hours to run respectively. Therefore if some one did break the build, it took at a minimum 2 1/2 but more like 3 1/2 hours to fix.

You had to find out who broke things, find out why, find the person and then get a fix in. And then you had to wait another 2/12 hours to see if the fix worked.

Because of this build feedback latency, we as a team ended up checking-in in a very synchronized way (say at 10.00am and then at say 3.00pm if on wanted to go home by 5.30pm) and because in a team of 12 people, some one is bound to break something at least once a day, we could check-in changes at most once, maybe twice a day.

Because you are only checking in once or twice a day, the changes tend to be larger and hence more likely to break the build. It becomes a bit of a negative feedback system of broken builds.

During this period the average time of breaking the build to it going green again could be about 2-4 hours but sometimes it was days.

People would then break the rules and check in when the build was broken, but this would often just confuse the situation and extend the build latency.

2 Months Ago

The long build times had been bubbling away for a long time and during dev speed week, Chris M and others did the work to split the build into a series of batches.

So instead of running 2000 tests in serial over 2/12 hours, we split them into 15 batches and ran them in parallel using the Bamboo Elastic Cloud support to create 15 remote agents.

This resulted in build run times of between 12-40 minutes. (Splitting into an even number of batches doesn't mean an even number of test run times it seems)

This reduced the build latency down to a more manageable level. Now you found out quicker that the build was broken but it was still talking about 1 hour to 1 1/2 hours to fix a broken build and the others in the team could not check in for that time period.

1 Month Ago

So about a month ago we dropped the rule about checking in when the build is broken.

However there are a series of caveats.

• When the one of the batches breaks, we as a team have to work out who broke it. We have 15 batches of builds and hence you may have broken 1 or more batches
• That person is then responsible to fix the build batch(es) in question.
• The other team members are free to check in while this happens.
• If the build continues to stay broken, or gets more broken (eg more and different tests start breaking) then a freeze is put in place to sort it out.
• Jed was appointed build champion to keep an eye on the situation and to chase up people.

The end result is that the build does not stay broken for long and the rest of the team can continue to make small changes to the code base.

Small changes are less likely to break the build and hence it tends to stay green for longer. Its a more of a positive feedback system.

We also added another little feature into the functional test framework that also helps.

We keep track of the tests that have failed ourselves instead of relying on JUnit/Bamboo test results. At the end of each test case run, we output a log message that tells us the state of the system.

It looks a bit like this :

===FTC Finished : TestSystemFieldLiterals.testType #2164 of 2361 (91.66%) : Errors 1 (0.042%)
   : Run time 4.59 seconds : Suite time 12656.18 seconds : HTTP Count 40
   : HTTP Time 2732ms : HTTP 100th 1637ms : HTTP 90th 88ms : HTTP 50th 18ms : HTTP Ave 0.07 ms/request
   : Max Mem 365428736 : Total Mem 365428736  : Free Mem 125712536
  1 test(s) failing so far :
      TestIssueDreams.testIssueLevelSecurity

You can tell by looking at the Bamboo live logs if the build is going to fail. If the log tells you that the one or more tests has failed, you can start working on the fix and check it in before the batch build finishes and hence reduce the build latency.

Conclusion

Conventional thinking is that a team should not check-in while the build is broken. The thinking goes that that you will not be able to keep track of the changes your team makes otherwise.

We have found that you can make changes while the build system is broken, within reasonable limits.

And the longer your build latency, the greater the payback of this type of development process.