Development guide

Here we describe some general guidelines for maintenance and development of gwloggeR.

General

gwloggeR is developed as part of a larger git-repository: https://github.com/DOV-Vlaanderen/groundwater-logger-validation.

So first we need to checkout this repository somewhere locally.

git checkout https://github.com/DOV-Vlaanderen/groundwater-logger-validation.git

Projects

The repository consists of 3 project roots:

./src/r which is mainly used for data analysis with R. The project file groundwater.rproj, when opened in Rstudio, will also load src/r/.Rprofile which will setup the environment for data analysis.
./gwloggeR is the gwloggeR package source repository used for development and testing. Open gwloggeR.Rproj with Rstudio.
./gwloggeR.data is a small convenience package developed for uniform data loading from the ./data/raw directory. Currently it has no explicit Rstudio project file.

Note that cross-linking of files between projects based on relative paths is allowed since all projects reside in the same repository.

Always double-check the .Rprofile file and adjust the paths accordingly.

Testing

There is a dedicated README about testing gwloggeR.

Before releasing a version, make sure to not only run the testthat procedures (Ctrl + Shift + T), but also the extensive analytics tests to make sure that the package results conform with past expected results (i.e. the package still operates as intended on previously analyzed data).

Documentation

The gwloggeR documentation is built using roxygen2. If you are using RStudio and roxygen2 is installed, then pressing Ctrl + Shift + B will:

Update Rd files (i.e. R documentation files)
Update NAMESPACE file
Update vignettes

This command will also install gwloggeR in the R lib\ directory and restart R.

On each update of gwloggeR source files, make sure to run this before committing.

README.Rmd

This is a special case that must be knitted to README.md. In RStudio one can use Ctrl + Shift + K. Knitting must be done before the website is built.

Website

For gwloggeR website we use pkgdown.

We do not use travis for automatic website deployment. Each time one updates files that have an impact on the website, one should manually execute the following commands:

pkgdown::clean_site()
pkgdown::build_site()

On each update of gwloggeR source files, make sure to run these commands before committing.

Deployment

Before deployment of a new version, certain steps need to be taken.

Update the Documentation.
Make sure you complete Testing, and also re-run the more elaborate analytics tests.
Make binary: devtools::build(path = './release/bin/win', binary = TRUE)
Update the News.md file. Each new version should be a top level section, besides the Development version and Future version sections.
Update the DESCRIPTION file, mainly the Version and Date tags.
Rebuild the Website and deploy it on the gh-pages branch. (This is the branch that GitHub uses as source for this gwloggeR website.)
Push both master and gh-pages branch to github.
Final step is to set the tag for the current version from the shell and push it to github.

# Note that git-shell can be opened from Rstudio.
git tag x.x.x # make sure to adjust the version.
git push --tags