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.
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()
.
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.
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()
).
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 π.
Create a new bcgov R project or package with a βready-to-goβ folder & file structure
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 = "[email protected]")
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 = "[email protected]")
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.
Initialise Git version control for my R project (without GitHub)
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 = "[email protected]")
Open a bcgov GitHub repository and synchronise with my R project
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 = "[email protected]")
Clone and contribute to an existing bcgov GitHub repository
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")
Add all or some of the required bcgov GitHub files to my R project
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 README.md
for the project?
use_bcgov_req(licence = "cc-by", rmarkdown = FALSE, coc_email = "[email protected]")
You can also add the individual required files as needed using:
use_bcgov_licence()
use_bcgov_readme()
use_bcgov_contributing()
use_bcgov_code_of_conduct(coc_email = "[email protected]")
Insert a licence header into my source file
Need to add that Apache 2.0 or Creative Commons License header to a source file? Just click-click:
You can also use insert_bcgov_apache_header()
or
insert_bcgov_cc_header()
.
Insert a bcgov project lifecycle badge into my README file
Want to add a lifecycle badge to your README file to indicate the current state of the project? Just click-click-click-click:
You can also use insert_bcgov_lifecycle_badge("experimental")
. Type
?insert_bcgov_lifecycle_badge
in the R console for the list of badge
options and other help.
There are several options you can specify in your .Rprofile
file to
customise the default behaviour when using the create_bcgov_
and
use_bcgov_
functions in bcgovr
.
-
bcgovr.coc.email
: Code of Conduct contact email address -
bcgovr.dir.struct
: Alternative project directory structure forcreate_bcgov_project()
. This should be specified as a character vector of directory (i.e.Β folders) and file paths, relative to the root of the project. Directories should be identified by having a trailing forward-slash (e.g.,"dir/"
).The default is:
c("R/", "data/", "out/", "01_load.R", "02_clean.R", "03_analysis.R", "04_output.R", "internal.R", "run_all.R")
.
To make use of these options, there should be a section in your
.Rprofile
file that looks something like this:
if (interactive()) {
options("bcgovr.coc.email" = "[email protected]")
options("bcgovr.dir.struct" = c("doc/", "data/", "results/", "src/01_load.R", "src/02_clean.R",
"src/03_analysis.R", "src/04_output.R", "src/run_all.R"))
}
The easiest way to edit your .Rprofile
is to run
usethis::edit_r_profile()
. It will open up the file in RStudio for
editing. Then save the file, restart R, and your settings will be saved.
This package is relatively stable and available for general use.
To report bugs/issues/feature requests, please file an Issue.
If you would like to contribute to the package, please see our CONTRIBUTING guidelines.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Copyright 2017 Province of British Columbia
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
This repository is maintained by Environmental Reporting BC. Click here for a complete list of our repositories on GitHub.