Badges

This section describes procedures to create, maintain, and update badges which ultimately appear on each repositories README page.

Source for badges

The source “svg” files for all badges are held in the “svgs” directory of github.com/ropensci-org/badges. New badges needs to be created there, generally by copying an existing badge and then editing the “svg” file. These files should be edited in a code (text) editor, and not in an image editor.

Statistical Software Review Badges

Badges for statistics packages include the version number of the Statistical Software Standards current at the time of package acceptance, coloured according to the “grade” of standards compliance (either bronze, silver, or gold). They look like this:

Each new version of the standards requires three corresponding badges to be added to the “svgs” directory of the “badges” repository, one for each colour. This can be done by simply copying one of the previous versions, and replacing the version numbers on the last two lines of each file with updated ones.

The ‘badges’ server and repository

The repository holding the source badges (github.com/ropensci-org/badges) serves the primary function of assigning an appropriate badge to each rOpenSci repository. These badges are served by our “badge server” which is deployed in the last step of the GitHub Action in that repository. The badge for each repository is uniquely identified by the issue number of the software-review repository, for example ‘badges.ropensci.org/222_stats.svg’ for the {epubr} package reviewed in issue number 222, which looks like this:

The rOpenSci package reviewed in issue number XYZ can then display the appropriate badge by simply linking to ‘https://badges.ropensci.org/XYZ_status.svg’.

The badge script

The server providing the badges reads them directly from the “pkgsvgs” directory of the “gh-pages” branch of that repository. This directory is populated by the main script, update_badges.rb. This script is called from the GitHub Action, and copies the appropriate badges from the source directory (“svgs”) in the main branch to the “pkgsvgs” directory in the gh-pages branch, renaming each according to the review issue number of each package.

Constructing and implementing new badges

The following steps describe the procedure which must be followed to construct and implement new badges.

  1. Design a new badge and save it in the “svgs” folder of the badges repository.

  2. Design a corresponding GitHub “approved” issue label in the main software-review repository. This label must begin with “6/approved-”, followed by the desired new text. Note the slash after “6” is forward, not backward!

  3. The bot then needs to be modified to recognise any new badges, like this code which processes statistics badges. That will then ensure that the approve command will also add the corresponding label to the issue thread.

  4. Modify the update_badges.rb script in the badges repository to recognise the new labels. The value of these new values will then generally be in the first field of the iss_peer_rev_files object, currently called “color”. The remainder of that script will then also need modifying to process entires with color values but no version values…

After updating the script, the new badges should be automatically deployed and assigned to the appropriate review issues.