Creating .accomplishment files

As you now know, .accomplishment files are crucial for the Accomplishments System. This is where all essential data about the accomplishment and how it is achieved is provided.

Technically, an .accomplishment file is a KeyFile containing of one group "accomplishment" and a bunch of values.

In practice, this means that .accomplishment files have following structure (This is not a working example, but a demonstration of syntax):

[accomplishment]
key = value
another_key = different value
title = My Accomplishment
multiline_key = This value is
    spread through
    multiple lines
    with each line having a tab at the beginning.
one_more_key: value

Note that both '=' sign and ':' can be used.

Keys can have a value spread across multiple lines, to do so, prepend all additional lines with a <TAB>.

Fields

There is a number of important fields you need to include in your accomplishment field. These include:

Basic information fields

• title - The name of your accomplishment. It must be human readable. This should describe in an active voice the activity (e.g. First Bazaar Branch Merged).

• description - A single line of summary that briefly explains what this accomplishment represents. This should be descriptive of the user achieving it (e.g. You had a bazaar branch merged).

• collection - This is the collection that the accomplishment is part of (e.g. ubuntu-community for the Ubuntu Community Accomplishments collection).

• category - The category this accomplishments belongs to.

  • If you are contributing accomplishments to an existing collection, make sure to reuse existing categories - see the CATEGORIES file in the lp:ubuntu-community-accomplishments branch to see which categories are used.

  • Multiple categories can be added and seperated by commas (e.g. category = Ask Ubuntu, Advocacy)

  • Sub-categories can be added with a colon (e.g. category = Ask Ubuntu:Answering would add the accomplishment in the Ask Ubuntu category and within the Answering sub-category).

• icon - The icon used for this trophy. Use just file name.

  • The icon is provided with accomplishments collection. More details concerning icons are in one of the later chapters.

Core settings

• depends - [optional] This field is used to specify a dependency. If the user has to accomplish something else to unlock this accomplishment, specify it here, providing the accomplishment's collection and name, using format <collection>/<name> e.g. ubuntu-community/filed-first-bug. You can specify multiple dependencies by seperating with commas (e.g. 'ubuntu-community/registered-on-launchpad, ubuntu-community/ubuntu-member`).

  • You can specify multiple dependencies by separating with commas (e.g. depends = ubuntu-community/registered-on-launchpad, ubuntu-community/on-planet-ubuntu).

  • Omit this field if your accomplishment does not depend on anything. If this field is used, the accomplishment will be locked by default.

• needs-signing - [optional] This is a very significant key. It decides whether this is a local or a global accomplishment. Only global accomplishments have to be signed by the validation server, so set this key to true if you want it to be a global accomplishment, otherwise set it to false, or do not include this key at all (preferred for local accomplishments).

• needs-information -[optional] A list of all extra-information fields that is required by this accomplishment.

  • Note that global accomplishments have to require at least one bit of extra-information, otherwise they make no sense.

Detailed information

• summary - A longer paragraph with a detailed description of the accomplishment. It should explain what this accomplishment represents, what is needed to complete it etc. You can use HTML here for formatting (but keep it simple: most accomplishments need only <b> and <i> tags).

  • This field can be spread across multiple lines (put a tab before each subsequent line) - see note in Introduction above.

• steps - [optional] Although optional, this field is heavily recommended. It should be a list of steps that need to be taken in order to complete this accomplishment. Add one step per line, and make sure to use "How To" style.

• tips - [optional] A set of recommended tips and tricks for being successful with this accomplishment - each in a new line.

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

• links - [optional] Add each link on a new line (this can be links to documentation, or another helpful resources).

• help - [optional] Other places where user can get help with this accomplishment - each in new line. Typically this is a link or an IRC channel.

Examples

Global

[accomplishment]
title=Filed First Bug
description=Filed your first bug in Ubuntu
collection=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

The code above is a complete working example of a global accomplishment.

Local

[accomplishment]
title=Beginner Minesweeper
description=Win a Small Gnomine game
collection=gnomine
category=Gnomine
icon=default.png
summary = You can achieve this accomplishment by finishing a Small game in Gnomine.
steps: Start Gnomine.
    Choose 8x8 (small) game.
    Find all hidden mines!
tips = You can learn the gameplay rules from Gnomine help.

Another example - this time it's a local accomplishment (note that needs-signing is omitted). It does not use all available keys, only what is reasonable in this particular case.

The next chapter will learn you how to prepare scripts for your accomplishment(s).