The Guide to Creating Your Accomplishments

Accomplishments sets structure

<-- Previous page (Creating accomplishment scripts) - - - - - Next page (Contributing to official accomplishment collections) --->

By default, all accomplishments installed on your system live in /usr/share/accomplishments. This directory contains two subfolders - accomplishments and scripts. Both these contain next level of directories, whose name equal to accomplishments set.

For example, let's consider ubuntu-community collection. It uses two directories: /usr/share/accomplishments/accomplishments/ubuntu-community/ and /usr/share/accomplishments/scripts/ubuntu-community/

Scripts directory

The scripts directory for a collection simply contains all script files for all accomplishments from this collection.

As an example, on my system there are files /usr/share/accomplishments/scripts/ubuntu-community/report-first-bug.py, /usr/share/accomplishments/scripts/ubuntu-community/registered-on-launchpad.py etc., and for another set there are files /usr/share/accomplishments/scripts/gnomine/win_small_game_in_15_seconds.py etc.

Accomplishments directory

The accomplishments directory is a bit more complicated. That's how a basic template looks like:

• /usr/share/accomplishments/accomplishments/SET

  • ABOUT
  • extrainformation
    • launchpad-email
    • something-else
  • trophyimages
    • icon1.png
    • icon2.png
  • en
    • A.accomplishment
    • B.accomplishment
    • C.accomplishment
  • pl
    • A.accomplishment
    • B.accomplishment
    • C.accomplishment
  • es
    • A.accomplishment
    • B.accomplishment
    • C.accomplishment

Let's have a closer look.

As you have already noticed, accomplishments can be easily localized. You have two options here:

• THe official Ubuntu collections (such as ubuntu-community-accomplishments are translated in Launchpad. Simply create you .accomplishment file in the en directory and we will enable it for translations in Launchpad. Simple!

• If you want to manually translate, simply put the accomplishments within a directory of a name equal to language code - the Accomplishments System will then use the directory of user's language. If there is no directory for the language selected by the user, Accomplishments System will fall back to set's default language, as specified in the ABOUT file.

The ABOUT file is just an obligatory text file that describes some general information about the set. It has a very simple structure, let's have a look at the ABOUT file from ubuntu-community set:

[general]
name = Ubuntu Community
langdefault=en

I guess it's self explanatory.

The trophyimages directory is used to store icons for accomplishments. If your accomplishment file has a key icon = something.png, then the Accomplishment System will look for it in the trophyimages directory. Be sure to include all required icons in your set!

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.
  
  Also, there are some stylistic recommendations we would like to suggest you. They are completely optional, but as we aim to have a consistently looking system, it would be nice if everyone kept the following guidelines in mind:

  • 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.

The last mysterious directory that has to be included in a collection is extrainformation. It has to be there, even if you don't use any extra-information (it should be empty in such case). This directory is meant to provide files with description of used extra-information fields.

For example, extrainformation/askubuntu-login would look like:

[label]
en = AskUbuntu login
pl = Login do AskUbuntu

[description]
en = The login used for AskUbuntu Q&A site
pl = Login używany na stronie AskUbuntu

This way the Accomplishments System will ask the user about his credentials with a human-readable message

Pro tip: You can get many templates for these files from https://launchpad.net/ubuntu-accomplishments-extra-information

And that's it, that's what an accomplishments set consists of.

Developing Your Collection

Although you should be now able to fully develop your accomplishments set on your own, there are some tips for that.

• It is good to maintain the directories structure in your development branch. This way it is easier to install the accomplishment to the system, and to manage them.
• It is recommended to provide a CATEGORIES file alongside ABOUT file, with a list of used categories, so that other contributors can re-use them.

• A the top-level of your branch there should be an install.sh file available, which is responsible for copying files to /usr/share/accomplishments. As an example template you can use the install.sh from ubuntu-community set:

#!/bin/bash
echo "Copying accomplishments to $1"
rm -rf $1/accomplishments/ubuntu-community
mkdir -p $1/accomplishments/ubuntu-community
cp -r ./accomplishments/ubuntu-community/* $1/accomplishments/ubuntu-community/

rm -rf $1/scripts/ubuntu-community
mkdir -p $1/scripts/ubuntu-community
cp -r ./scripts/ubuntu-community/* $1/scripts/ubuntu-community/
echo "Done!"

This script has to be run as follows: sudo sh install.sh /usr/share/accomplishments. If you are familiar with accomplishments set structure, you should understand this installer easily.

Remember: If you develop some global accomplishments, note that even if you install them properly, they will not be achievable, because the validation server is not aware of your accomplishments. If you want submit your accomplishments to the validation server, please contact us either by IRC (#ubuntu-accomplishments channel) or sending email to Ubuntu Contributors Team mailing list (https://launchpad.net/~ubuntu-accomplishments-contributors), and we'll consider your application.

• Creating a .deb package (or a PPA) for your set should be very easy if you maintain the directories structure. Look at lp:ubuntu-community-accomplishments branch, the ./debian directory there can be used as a template.

Final note

And that's it. If you want to create your own set, that's the end of the guide for you. Thanks for reading the guide, we hope to see some cool accomplishments from you soon! If you need further help, contact us via IRC (#ubuntu-accomplishments) or the mailing list.

For those who want to contribute to one of the official accomplishments collecctions, there is one more short chapter.

<-- Previous page (Creating accomplishment scripts) - - - - - Next page (Contributing to official accomplishment collections) --->