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