---
title: "General use of the package"
author: "Roel M. Hogervorst"
date: "`r Sys.Date()`"
output: 
    rmarkdown::html_vignette:
        toc: true
vignette: >
  %\VignetteIndexEntry{General use of the package}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

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](https://rmhogervorst.nl/cleancode/blog/2016/07/09/content/post/2016-07-09-submtting-to-cran-first-experience/)

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](https://docs.travis-ci.com/user/languages/r "a R-specific guide for travis"), 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. 

```{r scen 0}
library(badgecreatr)
badge_projectstatus("wip") # any of concept, wip, suspended, abandoned, active, inactive, unsupported
```

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)

```{r scen 1}
minimal_badges(status = "concept", license = "MIT",date = "2017-05-17")
```

### 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)


```{r scen 2, eval=FALSE}
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)

```{r , eval=FALSE}

```

### 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)

```{r, eval=FALSE}
# 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. 
