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 localy.

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

Projects

The repository consists of 2 project roots:

  • src/r/groundwater.rproj which is mainly used for data analysis with R. This project, when opened in Rstudio, will also load src/r/.Rprofile which will setup the environment for data analysis. Note that here one can also find test-cases for specific versions of gwloggeR. For example, src/r/outliers/outliers_v0.06_inbo contains all the results based on v0.06 (cf. #35) of the algorithm, which can be used as a manual regression test for new versions of gwloggeR.
  • gwloggeR/gwloggeR.rproj used for gwloggeR package development and testing.

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

Testing

There are a couple of unit tests in the tests directory. These tests are based on testthat and can be executed from Rstudio with Ctrl + Shift + T.

Mainly the hydrostatic pressure tests are important since they test the detection function based on a predefined small timeseries that has clear AO, LS and TC events.

Whenever you are tempted to type something into a print statement or a debugger expression, write it as a test instead.

Documentation

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

  • 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 commiting.

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 manualy execute the following commands:

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

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

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 analysis as described in Projects.
  • 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.
  • 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