SetStructure

Differences between revisions 11 and 19 (spanning 8 versions)
Revision 11 as of 2012-05-01 13:26:57
Size: 7806
Comment:
Revision 19 as of 2012-05-01 15:43:10
Size: 8058
Editor: 99-41-167-234
Comment:
Deletions are marked like this. Additions are marked like this.
Line 6: Line 6:
[[Accomplishments/CreatingGuide/Scripts|<-- Previous page (Creating accomplishment scripts)]] - - - - - [[Accomplishments|Next page (blah) --->]]

'''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!
<<BR>>
[[Accomplishments/CreatingGuide/Scripts|<-- Previous page (Creating accomplishment scripts)]] - - - - - [[Accomplishments/CreatingGuide/Contributing|Next page (Contributing to official accomplishment collections) --->]]
Line 13: Line 10:
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/` 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/`
Line 15: Line 12:
===== Scripts directory ===== == Scripts directory ==
Line 17: Line 14:
The scripts directory for a set simply contains all script files for all accomplishments from this set. The scripts directory for a collection simply contains all script files for all accomplishments from this collection.
Line 19: Line 16:
 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. 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.
Line 21: Line 18:
===== Accomplishments directory ===== == Accomplishments directory ==
Line 48: Line 45:
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 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 w
ithin 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.
Line 60: Line 60:
 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 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
Line 66: Line 66:
 * 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.
  * 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.
Line 70: Line 70:
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. 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.
Line 72: Line 72:
For example, extrainformation/askubuntu-login would look like: For example, `extrainformation/askubuntu-login` would look like:
Line 91: Line 91:
== Developing Your Set == == Developing Your Collection ==
Line 98: Line 98:
 {{{#!bash
{{{#!bash
Line 109: Line 110:
 }}}
 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.
}}}

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.
Line 117: Line 119:
<<BR>> == Final note ==
Line 120: Line 122:
For those who want to contribute to one of the official accomplishments sets, there is one more short chapter. For those who want to contribute to one of the official accomplishments collecctions, there is one more short chapter.
Line 122: Line 124:
[[Accomplishments/CreatingGuide/Scripts|<-- Previous page (Creating accomplishment scripts)]] - - - - - [[Accomplishments|Next page (blah) --->]] [[Accomplishments/CreatingGuide/Scripts|<-- Previous page (Creating accomplishment scripts)]] - - - - - [[Accomplishments/CreatingGuide/Contributing|Next page (Contributing to official accomplishment collections) --->]]

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 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 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! Smile :) 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) --->

Accomplishments/CreatingGuide/SetStructure (last edited 2012-05-01 15:43:10 by 99-41-167-234)