JOSS review - Installation instructions

[craig-willis]

Review issue: openjournals/joss-reviews#4707
Branch reviewed: release-0.2.4

Problem:
The JOSS guidelines require clear Installation instructions. I attempted to install dtrackr on a fresh Ubuntu 20.04 (via Docker) with R 4.2.1 and encountered several errors due to missing OS packages. These could be inferred from the required R packages, but it would be helpful to have a complete list in the installation instructions. Additional packages and OS dependencies were required to run the automated tests and could also be clearer.

What I had to install:

• R (of course)
• librsvg2-bin librsvg2-dev libv8-dev libcurl4-openssl-dev(via apt)

For automated tests:

• libxml2 (via apt)
• tidyverse

Consider adding a comprehensive list of dependencies as well as supported OS and R versions to the "Installing" section of the readme.

[robchallen]

Thank you. I've rewritten quite a lot of the README.Rmd file to address both this and to make the style of the README more formal.

Maybe you are aware of if already but I found pak::pkg_system_requirements() to be useful for this and I have signposted people to it for more unusual Linux distributions.

I've added a section on developing and running the automated tests

[robchallen]

Updated branch: joss-fixes-0.2.4.9000 (and main)

• rewritten much of the README.md to include a much expanded section on system dependencies. Due to a dependency problem I switched out staplr for pdftools which has changed the system requirements.

[craig-willis]

I ran into a very minor error during the pkgdown::build_site() noted below, but otherwise everything looks great.

For reference, here are my steps to confirm dtrackr installation on Ubuntu 20.04 via Docker. I tried to clarify which dependencies belong to each step, if useful.

1. Install r-base
2. Install tidyverse
3. Install dtrackr via CRAN
4. Install dtrackr via devtools
5. Install dtrackr from source
6. Run tests/coverage

1. Install r-base

docker run  -it ubuntu:focal bash

apt update

# Required to install r-base
apt install -y gnupg software-properties-common 

# Install r-base
apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 51716619E084DAB9
add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu focal-cran40/'

apt update
apt install -y r-base 

echo "TZ=$( cat /etc/timezone )" >> /etc/R/Renviron.site

2. Install tidyverse

apt install libcurl4-openssl-dev libssl-dev libxml2-dev

R
> install.packages('tidyverse')

3. Install dtrackr from CRAN

apt install librsvg2-dev libnode-dev

R
> install.packages('dtrackr')
> <Run basic usage example>
> remove.packages('dtrackr')

4. Install dtracker via devtools

apt install libharfbuzz-dev  libfribidi-dev libfreetype6-dev libtiff-dev libpoppler-cpp-dev 

R
> install.packages("devtools")
> devtools::install_github("terminological/dtrackr")
> <Run basic usage example>
> remove.packages('dtrackr')

5. Install dtrackr from source

apt-get install git

# Clone repo
git clone https://github.com/terminological/dtrackr
cd dtrackr

R
> install.packages(".", repos=NULL, type="source")

6. Run tests

> install.packages('pak')
> devtools::load_all()
> pak::local_system_requirements("ubuntu","20.04")
> install.packages(c("here","tidyverse","devtools","testthat","pkgdown"))
> devtools::run_examples()
> devtools::test()
...
== Results ======================================================================
Duration: 174.1 s

[ FAIL 0 | WARN 0 | SKIP 0 | PASS 144 ]

Build site

apt install make pandoc imagemagick libmagick++-dev \
 gsfonts default-jdk  zlib1g-dev libfontconfig1-dev \
 libjpeg-dev libpng-dev libgit2-dev 

> pkgdown::build_site()
...
Error in render_rmarkdown(pkg, input = input, output = output_file, output_format = format,  :
  Failed to render RMarkdown
Caused by error:
! error in callr subprocess
Caused by error:
! pandoc document conversion failed with error 83
In addition: Warning message:
Missing images in 'README.md': 'reference/figures/README-flowchart.png?raw=true'
i pkgdown can only use images in 'man/figures' and 'vignettes'

Install covr dependencies

apt install pandoc-citeproc

> install.packages('covr')
> covr::package_coverage(type="all", quiet = FALSE)

...
dtrackr Coverage: 83.60%
R/dot.R: 78.12%
R/dtrackr.R: 84.08%

[craig-willis]

Revised branch: joss-fixes-0.2.4.9000

Looks great (edit see above comment for details).