General use of the package

Roel M. Hogervorst

2018-06-04

Source: vignettes/general_use_of_the_package.Rmd

Badgecreatr was developed with myself in mind. I often create packages on Github and wanted to have a standardized way to add badges to the README file. In Github (and many other code sharing websites) the README.md file on top of the repository is automatically rendered as HTML (a normal webpage) and can be viewed by everyone in the browser with full markup.

I’ve written a blogpost about the older version of this package here

I’ve also added a vignette describing how you can add new badges to this package.

Badges or shields

Many projects have shields that signal the status of the project. When you make use of continuous integration (CI) tools such as travis-ci, you let the service rebuild and retest your package after every commit to Github. Travis has a badge that signals if the build passed or not. I’ve added extra information such as under what license the code is shared, the latest change in the package and what version the package has.

Keep in mind that I don’t create all of the badges (only 2 are of my invention), this package is just a convenient way to place badges in your readme.

Use cases

I realized that I don’t often use the package in its original form anymore, so the use cases might change. I’ve identified some cases.

  • [x] scenario 0: you just want to add a few loose badges
  • [x] scenario 1: starting a package with minimal badges.
  • [] scenario 2: base version but with logic added to seperate code part that tracks changes to R version, change date and versions.
  • [] scenario 3: you already have some badges, but you want to add newer ones (cran, rdocumentation, travis, etc).
  • [] scenario 4: you want to add certain badges, essentially a list of badges that you want, regardless of whats already there (so it should ignore badges, ignore if there is a travis file)
  • [] scenario 5: You don’t want a RMarkdown file, but a markdown file. Since markdown cannot process R, we add badges once.

Scenario 0: add a few loose badges

You just want to add a badge for projectstatus. All the badges start with badge_. So adding badges is as simple as typing badge_ and looking through the options.

library(badgecreatr)
badge_projectstatus("wip") # any of concept, wip, suspended, abandoned, active, inactive, unsupported
## [1] "[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](http://www.repostatus.org/badges/latest/wip.svg)](http://www.repostatus.org/#wip)"

The badge functions result in markdown that you can paste into your readme file. This would input the current date.

Scenario 1: starting a package with minimal badges

I imagin using this to add some quick badges that you might update later but it communicates the basic properties of the package:

  • Maturity (project status)
  • license
  • Last change (static)
minimal_badges(status = "concept", license = "MIT",date = "2017-05-17")
## [1] "[![Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept.](http://www.repostatus.org/badges/latest/concept.svg)](http://www.repostatus.org/#concept)[![license](https://img.shields.io/github/license/mashape/apistatus.svg)](https://choosealicense.com/licenses/mit/)[![Last-changedate](https://img.shields.io/badge/last%20change-2017--05--17-yellowgreen.svg)](/commits/master)"

Scenario 2: adding dynamic badges to your readme

You add badges that change everytime you re-knit your document so that everything stays up to date.

Communicate - Maturity (project status) - license - Last change - minimal r version - package version - travis badge (when a travis file is available) - codecov badge (when this is specified in the travis file)

dynamic_badges_minimal(license = "MIT", travisfile = TRUE, codecov = TRUE)

Scenario 3: you already have some badges, but you want to add other ones (cran, rdocumentation, travis, etc)

scenario 4: you want to add certain badges, essentially a list of badges that you want, regardless of what is already there (so it should ignore badges, ignore if there is a travis file)

# is not implemented yet.
place_badge_groups( 
    CI_status = c("travis", "rwin"), 
    versions = c("CRAN", "github"),
    stats = c("downloads, gh_stars"))

scenario 5: You don’t want a RMarkdown file, but a markdown file.

Since markdown cannot process R, we add badges once.