bcgovr <img src="tools/readme/logo.png" align="right" />

Overview

An R package to automate set up and sharing of R projects in bcgov GitHub following bcgov guidelines.

All B.C. Government employees are responsible for determining whether bcgov R source code can be shared on bcgov GitHub and for following the BC-Policy-Framework-For-GitHub.

You will need to ensure that Git is installed on your computer. To add your project to bcgov GitHub users need to have a GitHub account and be a member of the bcgov GitHub organisation.

Features

Functions

create_bcgov_project() & create_bcgov_package() Create a new—or populate an existing—R project or R package with folders & files that encourage best practice in scientific computing and with files that ensure the project meets bcgov GitHub requirements.

use_bcgov_git() Initialise Git version control for an R project and add files that ensure the project meets bcgov GitHub requirements.

use_bcgov_github() Open a bcgov GitHub repository and synchronise with an existing local R project and add files that ensure the project meets bcgov GitHub requirements. use_bcgov_github() requires that your project already be a Git repository. Use use_bcgov_git() to initialise a Git repository.

create_from_bcgov_github() Clone a bcgov GitHub repository and add files that ensure the project meets bcgov GitHub requirements.

use_bcgov_req() Add files to a new or existing R project to meet bcgov GitHub requirements. You can also add the bcgov required files individually using use_bcgov_contributing(), use_bcgov_licence(), use_bcgov_readme(), use_bcgov_readme_rmd(), use_bcgov_code_of_conduct().

RStudio bcgovr Project & Package Templates

The create_bcgov_project() or create_bcgov_package() and use_bcgov_git functions can be used simultaneously through the bcgovr Project & Package templates in the RStudio New Project dialogue box. The dialogue box allows a user to create a new R project or package with the option to select and individualise the required bcgov GitHub files and initialise Git version control.

RStudio Addins

The bcgovr package installs a set of RStudio Addins:

Insert the boiler-plate Apache 2.0 license header into the comments header of a source file (uses insert_bcgov_apache_header()).
Insert the boiler-plate Creative Commons Attribution 4.0 International License header into the comments header of a source file (uses insert_bcgov_cc_header()).
Insert a bcgov project lifecycle badge into an .Rmd or .md file to indicate the current state of a project (uses insert_bcgov_lifecycle_badge()).

Installation

You can install bcgovr directly from this GitHub repository. To do so, you will need the remotes package:

install.packages("remotes")

Next, install and load the bcgovr package using remotes::install_github():

remotes::install_github("bcgov/bcgovr")
library(bcgovr)

🎉 The authors of bcgovr acknowledge and thank the authors of the usethis R package—bcgovr uses usethis a lot. And by a lot, we mean every bcgovr function uses usethis under the hood 🚘.

Usage

I WANT TO…

<details> <summary> Create a new bcgov R project or package with a ‘ready-to-go’ folder & file structure </summary>

Create and open—or populate—a local R project using bcgovr::create_bcgov_project(). Be sure to either specify your local directory using the path argument, or setwd("C:/my-new-project") before running create_bcgov_project(). The template bcgovr folders and files and required bcgov GitHub files will be created in the new directory. For using different project templates, see the Options section below. Type ?create_bcgov_project in the R console for help.

create_bcgov_project(path = "C:/my-new-project", coc_email = "my.email@gov.bc.ca")

C:/my-new-project
├── 01_load.R
├── 02_clean.R
├── 03_analysis.R
├── 04_output.R
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── R
├── README.Rmd
├── data
├── my-new-project.Rproj
├── out
└── run_all.R

The create_bcgov_package() function is used the same way as create_bcgov_project() but will create all the folders & files to get started on creating an R package. Type ?create_bcgov_package in the R console for help. The R packages book by Hadley Wickham is a very useful resource if you are looking to create R packages.

create_bcgov_package(path = "C:/mynewrpackage", coc_email = "my.email@gov.bc.ca")

C:/mynewrpackage
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── DESCRIPTION
├── LICENSE
├── NAMESPACE
├── NEWS.md
├── R
├── README.Rmd
├── man
├── mynewrpackage.Rproj
└── vignettes
    └── mynewrpackage.Rmd

Users can also use the bcgovr Project & Package templates in the RStudio New Project dialogue box to create a new R project or package. The dialogue box provides the option to select and individualise the required bcgov GitHub files and initialise Git version control.

</details> <details> <summary> Initialise Git version control for my R project (without GitHub) </summary>

Put your local R project under version control by initialising a Git repository using use_bcgov_git()—this automatically completes staging and committing of the initial folders & files inside the project. The use_bcgov_git() function also ensures the project has the required bcgov GitHub files. Type ?use_bcgov_git in the R console for help.

use_bcgov_git(coc_email = "my.email@gov.bc.ca")

</details> <details> <summary> Open a bcgov GitHub repository and synchronise with my R project </summary>

Share your R project on bcgov GitHub using use_bcgov_github(). This requires that your project already be a Git repository—use use_bcgov_git() to initialise a Git repository if necessary. The use_bcgov_github() function creates a repository on bcgov GitHub and adds and synchronises your local project with the newly created bcgov GitHub origin. The use_bcgov_github() function also ensures the project has the required bcgov GitHub files. Type ?use_bcgov_github in the R console for help.

use_bcgov_github(organisation = "bcgov", coc_email = "my.email@gov.bc.ca")

</details> <details> <summary> Clone and contribute to an existing bcgov GitHub repository </summary>

Create a new local Git repository with a project or repository cloned from bcgov GitHub using create_from_bcgov_github(). The create_from_bcgov_github() function also ensures the project has the required bcgov GitHub files. Type ?create_from_bcgov_github in the R console for help.

create_from_bcgov_github(repo = "bcgov/bcgovr", destdir = "C:/my_directory")

</details> <details> <summary> Add all or some of the required bcgov GitHub files to my R project </summary>

Add the required bcgov GitHub files—a LICENCE, a README, a CODE OF CONDUCT and a CONTRIBUTING file—to any new or existing bcgov R project or package using use_bcgov_req(). Type ?use_bcgov_req in the R console for help.

You can use the licence, coc_email & rmarkdown arguments to change the default Apache 2.0 License, add your contact details to the Code of Conduct, or decline a README.Rmd file—maybe you only want a R

Bcgovr

Install / Use

README