SetStructure

Differences between revisions 9 and 10
Revision 9 as of 2012-05-01 12:57:55
Size: 6459
Comment:
Revision 10 as of 2012-05-01 13:09:21
Size: 6916
Comment:
Deletions are marked like this. Additions are marked like this.
Line 109: Line 109:
 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 that installer easily.  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).

The Guide to Creating Your Accomplishments

Accomplishments sets structure

This page is under construction. This guide is not yet complete!

Note: Following information is valid only for Accomplishments System 0.1, and most likely will change for 0.2. But don't let it stop you from developing accomplishments, we promise that switching from 0.1 to 0.2 will be easy!

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 set. It will use two directories: /usr/share/accomplishments/accomplishments/ubuntu-community/ and /usr/share/accomplishments/scripts/ubuntu-community/

Scripts directory

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

  • So, as an example, I 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 should put 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 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:

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

The last mysterious directory that has to be included in a set is extrainformation. It has to be there, even if you does not use any extra-information (it should be empty then). 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 Smile :-)

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 Set

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

Accomplishments/CreatingGuide/SetStructure (last edited 2012-05-01 15:43:10 by jonobacon)