Changes between Initial Version and Version 1 of BadgeDoc

Timestamp:

Dec 23, 2013, 11:46:03 AM (11 years ago)

Author:

davea

Comment:

--

BadgeDoc

@@ +1 @@
+= Badges =
+
+'''Badges''' are symbols of accomplishment by volunteers or teams -
+for example, how much computing they're contributed.
+Badges are shown as icons on project web sites.
+In the future, they may also be shown in client GUIs and statistics sites.
+
+BOINC provides a general mechanism for defining and assigning badges.
+You can create badges for whatever accomplishments you want -
+average credit, total credit, length of participation,
+number of message-board posts, etc.
+
+The data associated with a badge includes:
+ * A name (used to identify the badge internally; not shown to users)
+ * The URL of an image file.
+   The image will be sized on display (currently 48 pixels high).
+   Make it somewhat larger than this, e.g. 300x300 pixels.
+   For flexibility, use a PNG with transparent background.
+ * A title - a short phrase that explains the accomplishment
+   for which the badge is granted.
+
+Badges are granted (or removed) by a PHP script that you would typically
+run as a periodic task from your config.xml file.
+
+== The default badges ==
+
+By default (for new projects) there are badges
+for the top 1%, 5%, and 25% of recent average credit (RAC).
+They are represented by gold, silver, and bronze medal images, respectively,
+and are assigned to both users and teams.
+
+== Writing a badge-assignment script ==
+
+The script that assigns the default badges is here:
+http://boinc.berkeley.edu/gitweb/?p=boinc-v2.git;a=blob;f=html/ops/badge_assign.php
+
+You can use this script as a template for writing your own.
+
+The script uses the following utility functions, defined in '''html/inc/util_ops.inc''':
+{{{
+get_badge($name, $title, $image_url)
+}}}
+Return a PHP object representing the badge with the given name, title, and image file URL.
+Badge descriptions are stored in the MySQL database;
+this function creates a DB record if it's not already there.
+
+{{{
+assign_badge($is_user, $item, $badge)
+}}}
+Assign the given badge to the given user or team;
+'''item''' is either a user ID or a team ID.
+
+{{{
+unassign_badges($is_user, $item, $badges, $k) 
+}}}
+Remove badges from a given user or team.
+'''$badges''' is a vector of badges to remove.
+Remove all except the '''$kth''' one;
+if '''$k''' is negative, remove them all.
+
+Using these utility functions, the script works as follows:
+
+ * Use '''get_badge()''' to get the gold, silver, and bronze badge objects.
+ * '''get_percentiles()''': compute the top 1, 5, and 25 percentile values of RAC.
+ * '''assign_badges()''': loop over the set of all items (users or teams).
+   This is done 1000 items at a time to limit memory usage.
+ * For each item, compare its RAC with the RAC percentiles,
+   and determine which badge to assign (if any).
+   Assign that badge, and unassign the others.
+
+These steps are performed first for users, then for teams.
+