This page explains how you can contribute different Ubuntu Accomplishments to be used as part of the accomplishments system. Fortunately creating accomplishments is simple. Let's get started.

If you want to create a set of accomplishments for your community see this guide.

Before you Begin

You should ensure that you have the Ubuntu Accomplishments system installed and ready to run. You can find out how to do this on this page.

Getting The Ubuntu Accomplishments Collection

We keep all of the Ubuntu Accomplishments in a branch in Launchpad. Get it with:

bzr branch lp:ubuntu-community-accomplishments

Inside the branch you will see a accomplishments and scripts directory. We need to create both an .accomplishment file as well as provide a script.

You should ensure that your PYTHONPATH points to the ubuntu-accomplishments-system branch:

export PYTHONPATH=$PYTHONPATH:/path/to/ubuntu-accomplishments-system

How Accomplishments Work

An accomplishment is a notable achievement that someone can accomplish in the community. These should be real accomplishments of substance (e.g. Filed my first bug, became an Ubuntu Member, or translated my first string) and not based upon potentially meaningless traffic (e.g. 50 comments on a but report, 500 posts to a forum).

Each accomplishment has two parts to it:

• .accomplishment - this is a file that describes what the accomplishment is, how to get it, which other accomplishments it depends on etc.
• A script - the script is run to check if the user actually accomplished the thing or not.

In the ubuntu-community-accomplishments branch you can see an accomplishments and scripts directory, each of which has an ubuntu-community directory where the respective .accomplisment and scripts files live.

To create a new accomplishment all you need to do is create an .accomplishment file (e.g. first-translation.accomplishment) and matching script (e.g. first-translation.py) for the trophy that people can achieve.

Let's look at how to do this now.

Creating an Accomplishment

Let's walk through how to create an accomplishment.

Create an .accomplishment file

First create the .accomplishment file in the accomplishments/ubuntu-community directory of the ubuntu-community-accomplishments branch. You might want to copy another file and change the information.

This needs to have a unique name (e.g. first-translation.accomplishment). Remember this unique name, we will need to call our script the same name later (e.g. first-translation.py).

The file contains information about this particular accomplishment. There are a number of set fields you should add under a [accomplishment] block:

• title - a human readable name for the accomplishment.

• description - a single line summary of what the accomplishment is.

• application - this is the set that the accomplishment is part of (e.g. 'ubuntu-community' for the Ubuntu Community Accomplishments set).

• category - add what category this fits into. See the CATEGORIES file in the branch to see existing categories that have been used (add another one if what you need does not exist). Only one category can be set currently, but in the future we want to support multiple categories.

• icon - the icon you want to use for the trophy which refers to a file in the accomplishments/trophyimages directory. If you want to create a new icon, be sure to include the new icon in your merge proposal.

• depends - if your accomplishment requires another accomplishments to be completed before yours can be (and is thus locked), specify what other accomplishment is required here. This needs to be specified in the format application>/</accomplishment (e.g. ubuntu-community/filed-first-bug).

• needs-signing - set this to true - this means the accomplishment has a companion script that needs to be run for it to be verified (this applies to all accomplishments that are part of a community).

• needs-information - you can specify multiple of these identifying what information you need for the associated script to run. More on this later.

• summary - this is a longer HTML infused paragraph summarizing what needs to be done to achieve the accomplishment. You can break this into paragraphs by including a tab at the beginning of each new paragraph.

• steps - add each step in a new line to describe how to achieve this accomplishment.

• tips - a set of recommended tips and tricks (each one added on a new line) for being successful with this accomplishment.

• pitfalls - a set of things the user should avoid while persuing this accomplishment (each one added on a new line).

• links - add each link on a new line (this can be links to documentation).

• help - describe each help resource where users can find help on a new line.

An example:

[accomplishment]
title=Filed First Bug
description=Filed your first bug in Ubuntu
application=ubuntu-community
category=QA
depends=ubuntu-community/registered-on-launchpad
needs-signing=true
needs-information=launchpad-email
summary = A bug is a defect in a piece of software. Filing a bug means that you let the Ubuntu project know about one of these defects. There are a few different ways in which you can file a bug, but we recommend you use a tool called <tt>ubuntu-bug</tt> that comes pre-installed on all Ubuntu systems. You can file a bug in a more graphical way by using the Report a Problem option in the Help menu of an application.
steps: Open up a terminal by clicking the Ubuntu button and typing 'terminal' into the dash.
        Type in <tt>ubuntu-bug</tt> and then the name of the package you want to file a bug against (e.g. 'ubuntu-bug unity' for Unity).
        Follow the instructions in Launchpad.
tips: Be sure to add a good description for your bug.
        Include a set of steps to follow to show the developer how to re-produce the bug.
pitfalls: Don't file a bug if it has already been filed.
        Don't respond to bugs with "me too". This is not helpful to developers.
links: http://www.ubuntu.com
        http://www.jonobacon.org
help = #ubuntu-testing on Freenode

Save this file. We now need to create our companion script.

Using and Creating Accomplishments Icons

An important of any accomplishments is having an attractive looking icon. Fortunately, adding icons for your accomplishments is really simple.

In your accomplishment you have the icon field in which you can specify an icon. For example:

icon=default.png

Every accomplishment set should include a default.png icon. Icons for your accomplishments should be added to the accomplishments/trophyimages directory.

Let's look at how to create an icon.

Creating Your Icon

We ask that you use our icon template for creating your icon so it looks consistent with the rest of the system. You can download the SVG file for the template by clicking here: http://ubuntuone.com/28q8Z4azh69joKUFTSs59y

If you are creating an Ubuntu accomplishment icon, download the Ubuntu themed template here: http://ubuntuone.com/2JmpY5xZkfanhNfO37JRts

Use an SVG editor such as Inkscape to create your icon.

When your icon is ready export it to a .png file at 200 pixels high and 137 pixels wide.

Stylistic Recommendations

when creating your icon please bear the following guidelines in mind:

• Again, please use the shape of the template provided above, but feel free to customize it using the imagery, branding, and style of the area that the accomplishment is part of (e.g. how we have the Ubuntu accomplishments reflect the Ubuntu color and brand guidelines).

• Try not to have a different icon for every accomplishment: instead have your accomplishment icons reflect the categories of accomplishments in your accomplishments set.

• As with the Ubuntu guidelines, we recommend you have a consistent color for all of your icons and then have a different for the different types of accomplishment.

Create a script

With your .accomplishment file ready, you now need to create a script that will do the work of checking to see if you accomplished the thing described.

You will need to write you script in Python today; although we hope to open this up to other languages in the future.

Identifying Required Information

Every script needs some information for it to verify if the accomplishment was achieved (e.g. such as the user's Launchpad email address).

To ensure that we have consistancy across all accomplishments and translations for the information requested, you can see the different types of information you can ask for in the ubuntu-community-accomplishments/accomplishments/ubuntu-community/extrainformation directory. The vast majority of accomplishments only need launchpad-email to run. This file includes information about this piece of required information and the various translations.

If you need another piece of information, grab the following branch:

bzr branch lp:ubuntu-accomplishments-extra-information

Inside this archive are a series of files that contain translations and information for the different types of information you can request. Copy the files you need into the extrainformation directory. If a piece of information is not available in the branch, just create it and contribute it to the branch.

Now ensure your needs-information line in the .accomplishment file includes the files you copied to extrainformation. As an example, ensure that launchpad-email is copied there and then inside the .accomplishment file specify:

needs-information: launchpad-email

Fortunately, most of these files should already be copied into the extrainformation directory.

When a particular piece of information is requested (e.g. launchpad-email) that we don't have the value for (e.g. my email address on Launchpad), the client app will ask for it.

Creating the script

Your your script should use the following import:

    from accomplishments.daemon import dbusapi

You can then use the getExtraInformation to query this information from the daemon by asking for 'Launchpad Email':

api = dbusapi.Accomplishments()
f = api.getExtraInformation("ubuntu-community", "launchpad-email")

This function returns a list.

You should now check to see if the data exists, if it doesn't, exit with error code 4:

if bool(f[0]["launchpad-email"]) == False:
    sys.exit(4)
else:
    email = f[0]["launchpad-email"]

Now write your script to check if the accomplishment was achieved. Based upon the outcome you should exit with one of the following exit codes:

• 0 - the accomplishment was achieved.

• 1 - the accomplishment was not achieved.

• 2 - something went wrong when trying to run the script (e.g. the network is down).

Testing and Debugging Your Script

Testing and debugging is simple. Open one terminal and run the daemon for the accomplishments system:

cd ubuntu-accomplishments-system
./bin/rundaemon.sh

In another terminal go the scripts directory where you are creating your new accomplishment and run it like any other python script:

cd ubuntu-community-accomplishments/scripts/ubuntu-community
python <my-script>.py

Remember, when the script runs it will run getExtraInformation() and this function looks to see if the information requested exists in your ~/.local/share/accomplishments/trophies/.extrainformation directory (this is where the app saves the information it asks for).

The script will run like any other Python script, and you can use print statements to check that it is working properly for you.

Before you submit the script for inclusion, please remove all print statements.

Loading your new Accomplishments

When you accomplishment is ready, you can now install it (remember, you created it in the ubuntu-community-accomplishments branch, and we need to copy it to our main accomplishments directory where our collection of accomplishments live.

To do this, just install it like you did when you set up the Ubuntu Accomplishments system:

cd ubuntu-community-accomplishments
./install.sh /home/<you>/accomplishments

You can now run the main accomplishments app to test it.

Remember, before your accomplishments can be verified on the server, you need to submit it so I can install it on the server and test!

Contributing Your Accomplishment

Before you contribute your branch, please ensure that you include the following three files:

• install.sh - this install the accomplishments from your branch directory to the location of the user's accomplishments.

• README - provide some context around what is in the accomplishments and which other packages are required for installation.
• CATEGORIES - list the categories you are using in your categories here.

See the ubuntu-accomplishments branch to see an example of each of these files.

To contribute your accomplishment add the above files (and be sure to update CATEGORIES and NEEDSINFORMATION if you added new items there) and then run:

bzr add

Now commit your changes:

bzr commit

Finally push your changes to Launchpad:

bzr push lp:your-lp-username/ubuntu-community-accomplishments/your-branch-name

Now go to the branch in Launchpad and propose it for merging into `lp:ubuntu-community-accomplishments.