Changes between Initial Version and Version 1 of BadgeDoc


Ignore:
Timestamp:
Dec 23, 2013, 11:46:03 AM (11 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BadgeDoc

    v1 v1  
     1= Badges =
     2
     3'''Badges''' are symbols of accomplishment by volunteers or teams -
     4for example, how much computing they're contributed.
     5Badges are shown as icons on project web sites.
     6In the future, they may also be shown in client GUIs and statistics sites.
     7
     8BOINC provides a general mechanism for defining and assigning badges.
     9You can create badges for whatever accomplishments you want -
     10average credit, total credit, length of participation,
     11number of message-board posts, etc.
     12
     13The data associated with a badge includes:
     14 * A name (used to identify the badge internally; not shown to users)
     15 * The URL of an image file.
     16   The image will be sized on display (currently 48 pixels high).
     17   Make it somewhat larger than this, e.g. 300x300 pixels.
     18   For flexibility, use a PNG with transparent background.
     19 * A title - a short phrase that explains the accomplishment
     20   for which the badge is granted.
     21
     22Badges are granted (or removed) by a PHP script that you would typically
     23run as a periodic task from your config.xml file.
     24
     25== The default badges ==
     26
     27By default (for new projects) there are badges
     28for the top 1%, 5%, and 25% of recent average credit (RAC).
     29They are represented by gold, silver, and bronze medal images, respectively,
     30and are assigned to both users and teams.
     31
     32== Writing a badge-assignment script ==
     33
     34The script that assigns the default badges is here:
     35http://boinc.berkeley.edu/gitweb/?p=boinc-v2.git;a=blob;f=html/ops/badge_assign.php
     36
     37You can use this script as a template for writing your own.
     38
     39The script uses the following utility functions, defined in '''html/inc/util_ops.inc''':
     40{{{
     41get_badge($name, $title, $image_url)
     42}}}
     43Return a PHP object representing the badge with the given name, title, and image file URL.
     44Badge descriptions are stored in the MySQL database;
     45this function creates a DB record if it's not already there.
     46
     47{{{
     48assign_badge($is_user, $item, $badge)
     49}}}
     50Assign the given badge to the given user or team;
     51'''item''' is either a user ID or a team ID.
     52
     53{{{
     54unassign_badges($is_user, $item, $badges, $k)
     55}}}
     56Remove badges from a given user or team.
     57'''$badges''' is a vector of badges to remove.
     58Remove all except the '''$kth''' one;
     59if '''$k''' is negative, remove them all.
     60
     61Using these utility functions, the script works as follows:
     62
     63 * Use '''get_badge()''' to get the gold, silver, and bronze badge objects.
     64 * '''get_percentiles()''': compute the top 1, 5, and 25 percentile values of RAC.
     65 * '''assign_badges()''': loop over the set of all items (users or teams).
     66   This is done 1000 items at a time to limit memory usage.
     67 * For each item, compare its RAC with the RAC percentiles,
     68   and determine which badge to assign (if any).
     69   Assign that badge, and unassign the others.
     70
     71These steps are performed first for users, then for teams.
     72