sos4R developer documentation

Build Status AppVeyor build status

This file contains information for developers of the R package sos4R. Documentation for users can be found in the package’s vignettes (see browseVignettes("sos4R")).

sos4R is developed on GitHub using the fork & pull development model. The main repository’s issue tracker is used to coordinate development.

The master branch represents the current version that is published on CRAN, the dev branch is the current development version.

Requirements

  • System packages (e.g., on Ubuntu 18.04)
    • r-base-dev
    • libxml2-dev
    • libgdal-dev
    • libproj-dev
    • libgeos-dev
    • texinfo
    • texinfo-doc-nonfree
    • texlive (TinyTex is recommended!)
    • texlive-base
    • texlive-fonts-recommended
    • texlive-fonts-recommended-doc
    • texlive-generic-recommended
    • texlive-latex-base
    • texlive-latex-base-doc
    • texlive-latex-extra
    • texlive-latex-recommended-doc
    • texlive-pstricks
  • R packages (see fields Depends and Suggests in DESCRIPTION)

Contribute

Please get in touch with the community contact of the geostatistics community and read the Get Involved page if you want to become a contributor – contributions are welcome!

You can also dive right in and join the chat room: Join the chat at https://gitter.im/52North/sos4R

Development, versions, and branches

  • Roadmap and release planning is done in projects.
  • The master branch is up to date with the version on CRAN. Bugfixes should be based on this branch.
  • Tasks are developed in task or feature branches based on the dev branch. Pull requests are sent from the features branches to the dev branch once they are complete.
  • Feature ideas as issues tagged “enhancement”.
  • Bugs are issues tagged as “bugs”.
  • The package uses semantic versioning.
    • The current development version should start with .9000 after the patch version, see R packages versioning.
    • The development version can be increased extensively, e.g. with each non-trivial commit.
    • The version must be changed in the files DESCRIPTION and man/sos4R-package.Rd (which is important for releases).
    • Bugfix versions can be used extensively (for several, or even just one bug) to show users that errors are resolved.
    • Minor versions shall include several major bug fixes or a considerable addition of tested and working functionality.
    • Code changes that possibly break existing code shall only be released with a major version change and should be discussed in the developer community beforehand.
  • You can inspect the changes between releases very comfortably on the CRAN GitHub organization: https://github.com/cran/sos4R/commits/master

Users may install the current development version or local branches using respective functions of devtools.

Documentation

News

The latest changes for every version are documented in the file NEWS.md in the package root directory. Open a preview with pkgdown::build_news().

R function documentation

Package documentation is based on .Rd files (regarding switch to roxygen see https://github.com/52North/sos4R/issues/21). The file NAMESPACE is not managed by roxygen2 either.

Update website

Knit README.Rmd to create README.md.

Run pkgdown from the package directory each time you release your package:

pkgdown::build_site()

Build vignettes

The vignettes should build as part of the docs website or package check process. To build single vignettes manually you can use

rmarkdown::render("vignettes/sos4R.Rmd")

or

pkgdown::build_article("sos4R-vignette-04-extensions")

Note that some of the vignettes are not build as part of the package check since there are timeout problems, but only as part of the pkgdown website. These vignettes do not have a vignette: element in the Rmd document header and are ignored via .Rbuildignore.

Package structure

sos4R follows the regular R extension package structure. General documentation about R package development can be found at the following two websites.

/R

The actual source files in the /R directory follow a naming schema:

  • Class-[NamespacePrefix].R files contain class definitions, which are grouped by OGC specification namespace, like classes for XML types in Class-GML.R, but also generic classes as in Class-SOS.R.
  • constants.R contains … constants! No XML element name or parameters string shall be specified outside of this class; constants shall not be changed by the user. Please reconsider every time you write a character string in the code if it should not be a constant. Names of XML types and elements shall always be constants, attribute names can be constants. This file also contains the lists of supported features, like result models and connection methods. Use accessor functions where needed.
  • defaults.R contains default settings and values, including parsers, encoders, etc., as well as accessor functions to the defaults
  • Generic-methods.R contains all generic method definitions except the ones for accessor functions
  • [NamespacePrefix]-methods.R contains methods and used (helper or delegate) functions grouped by OGC specification namespace for…
    • creation methods (constructor functions)
    • encoding methods
  • [NamespacePrefix]-methods-parsing.R contains parsing methods grouped by OGC specification namespace; if there is a very limited number of parsing functions and the file is not very long, the parsing functions may also be in the file [NamespacePrefix]-methods.R.
  • [NamespacePrefix]-methods-coercion.R contains coercion methods grouped by OGC specification namespace to map from sos4R’s classes to R objects
  • [NamespacePrefix]-methods-accessor.R and [NamespacePrefix]-methods-util.R contains accessor functions (which should be used over direct slot access) or utility functions (which are not well defined what they are in contrast to non-utility functions…) grouped by OGC specification namespace
  • SOS-methods.R contains the functions for the operations, like getCapabilities(sos:SOS), and the function that actually does the sending of the request, sosRequest(…).
  • SOS-methods-accessor.R contains accessor functions.
  • SOS-methods-util.R contains a lot of convenience and accessor functions, and should be used to keep the file SOS-methods.R lucid.
  • SOS-methods-plotting.R contains plotting functions.
  • PrintShowStructureSummary-methods.R contains functions to override print, str, summary functions and the like; these may go in this file or also into the file where the respective class is defined.
  • Wrapper-methods.R contains methods and functions for the convenience wrapper functions for easier data access.

/sandbox

In addition to the regular directories, the /sandbox folder contains a wild list of R scripts with tests and demos etc. Code in this directory is not exported from the package but is used during development to test during the implementation of (new) functionality. Please consider using this extensively as a history to be able to resolve problems that occurred before and to document what is working and what not. It is also recommended to run related tests again after (even minor) changes in the code.

  • testing.R contains tests done during the development of certain functions and is a very good opportunity to (re-)check functionality and keep a history of functionality that is working (at some point in time at least…).
  • testing-SOSs(-2.0).R contains tests of connections to different types of SOS and different SOS instances.

Naming of functions, defaults, and constants

The following guidelines are a non extensive list of naming rules that were used within the package. Please also browse through the code files before starting to develop new functions to get to know the structures that are already in place so that a good user experience can be ensured.

  • Defaults: sosDefaultXYZ, e.g. sosDefaultCharacterEncoding
  • Defaults with accessor function: Follows the same rules, but add a point to the actual variable so that it is not exported and start the function with a capital letter, e.g. .sosDisabledParsers and SosDisabledParsers()
  • Constants: Constants for names of XML elements start with a lowercase character string of the namespace prefix, a unique name of the element (where parts like “type” and special characters may be left out, and other descripte elements may be added for clarity), and end with Name, e.g. gmlEnvelopeName <- "Envelope", ogcGeometryOperandLineStringName <- "gml:LineString", or ogcTempOpTMEqualsName <- "TM_Equals".
  • Supported features: The supported features, like connection methods and supported response modes, shall be accessible by functions starting with SosSupported, e.g. SosSupportedConnectionMethods().
  • Accessor functions: Shall start with sos, e.g. sosOfferings(sos:SOS).
  • Functions to access default values, especially lists and functions with merging feature: Shall start with Sos, e.g. SosEncodingFunctions().

Classes

Data models, i.e. requests and responses, are modelled as S4 classes. Documentation can be found at the following sites (and others):

Troubleshooting

Examples

Make sure that the examples, i.e., code in .Rd files, work without internet connections. sos4R has been called out for that a few times for breakign CRAN policy, which is not our intention. One way to make sure the examples work without internet connection is to run a container without network and R CMD check in there - see comments in docker/Dockerfile for instructions how to do that.

Tests

Tests are implemented with testthat. Run them with “Ctrl + Alt + T” in RStudio, with the RStudio UI via Build &rarr; More &rarr; Test Package, or with

devtools::test()

Using Docker

The docker folder contains a Dockerfile that can be used to set-up an isolated container just for sos4R development. This includes all required dependencies, RStudio as webapplication, and devtools.

  1. Clone this repository.

  2. Change to the docker subfolder in any terminal of your choice.

  3. Perform the following command to build the image locally:
    docker build -t sos4r-rstudio-dev:$(date +%Y-%m-%d) ..
    On windows, you need to replace $(date +%Y-%m-%d) with something useful, like 2019-02-27.

  4. Start the image as new container using the following command:

    docker run --name=sos4r-dev --env PASSWORD=r --publish 8787:8787 --volume /YOUR_PATH_TO/sos4R/:/home/rstudio/sos4R -d    sos4r-rstudio-dev:2019-02-27

    You can start and stop the container by its name sos4r-dev.

  5. Point your browser to http://localhost:8787/.

  6. Login with Username rstudio and Password r.
    If the password is not secure enough, please delete the container via docker stop sos4r-dev; docker rm sos4r-dev and re-run the above docker run ... with a different value for PASSWORD.

  7. Open the sos4R project via menu File → Open Project → open folder sos4R → select sos4R.Rproj.

  8. Start developing.

Add features

See Versions and Branches for information about the release flow. In your new feature branch, implement the feature. Add tests.

Releases

A new release shall be uploaded to CRAN after testing and under the following procedure:

  • Install the current version of the package from source
  • Run the tests locally and resolve all problems
  • Run a check locally, e.g., devtools::check(document = FALSE) or “Build → Check” in RStudio; fix all errors, warnings, and notes
  • Update NEWS.md file based on latest commits, add missing changes/updates/notable things
  • Update the Date field in the DESCRIPTION file to match the release date
  • Update version and date in man/sos4R-package.Rd
  • Update version in DESCRIPTION
  • Update version number in NEWS.md
  • Create a PR from dev to master and check the CI status, fix all problems (for quick bugfix releases, you may create a PR from your fork or a bugfix branch straight to master)
  • Run checks again and fix all problems
    • In the parent directory of the project: R CMD build sos4R; R CMD check --as-cran sos4R_<version number>.tar.gz should have no errors, warnings, or notes
    • revdepcheck::revdep_check() for checking reverse dependencies
    • devtools::check_win_release() and devtools::check_win_devel() for testing Windows using CRAN infrastructure
    • rhub::check_for_cran(email = <...>) for testing for CRAN submissions using RHub infrastructure
    • (optional) rhub::check(email = <...>) for running checks on different operating systems
  • Regenerate the website with options(rmarkdown.html_vignette.check_title = FALSE); pkgdown::build_site() and re-knit README.Rmd, commit changes
  • Push changes to dev branch
  • Read and follow http://cran.r-project.org/web/packages/policies.html and http://r-pkgs.had.co.nz/release.html#release-check again, make necessary changes
  • Merge the PR
  • Update your local master to upstream’s master branch
  • Do the actual release with devtools::release() (which will ask you again if you did many of the steps before)
  • Wait for the confirmation link (via email) and fill in the online submission form
  • Wait for the good news, check where the package is in the queue with foghorn::cran_incoming(pkg = "sos4R")
  • When available on CRAN:
    • Create a git tag with the version number using the letter v followed by the version number (see above, must match DESCRIPTION), e.g. v1.2.3, and push it to the main repository
    • Create a release on GitHub based on the new tag, named just as the version tag, see the file CRAN-RELEASE for the precise commit
    • Remove the file CRAN-RELEASE
    • Checkout the dev branch
    • Merge upstream/master
    • Update the version in DESCRIPTION to a new development version, e.g. from 0.3.0 to 0.4.0.9000
    • Email on 52N mailing list(s) (coordinate with 52N staff)
    • Tweet