master branch represents the current version that is published on CRAN, the
dev branch is the current development version.
masterbranch is up to date with the version on CRAN. Bugfixes should be based on this branch.
devbranch. Pull requests are sent from the features branches to the dev branch once they are complete.
.9000after the patch version, see R packages versioning.
man/sos4R-package.Rd(which is important for releases).
Users may install the current development version or local branches using respective functions of
The latest changes for every version are documented in the file
NEWS.md in the package root directory. Open a preview with
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
README.Rmd to create
Run pkgdown from the package directory each time you release your package:
The vignettes should build as part of the docs website or package check process. To build single vignettes manually you can use
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
sos4R follows the regular R extension package structure. General documentation about R package development can be found at the following two websites.
The actual source files in the
/R directory follow a naming schema:
Class-[NamespacePrefix].Rfiles 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
constants.Rcontains … 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.Rcontains default settings and values, including parsers, encoders, etc., as well as accessor functions to the defaults
Generic-methods.Rcontains all generic method definitions except the ones for accessor functions
[NamespacePrefix]-methods.Rcontains methods and used (helper or delegate) functions grouped by OGC specification namespace for…
[NamespacePrefix]-methods-parsing.Rcontains 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-coercion.Rcontains coercion methods grouped by OGC specification namespace to map from sos4R’s classes to R objects
[NamespacePrefix]-methods-util.Rcontains 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.Rcontains the functions for the operations, like getCapabilities(sos:SOS), and the function that actually does the sending of the request, sosRequest(…).
SOS-methods-accessor.Rcontains accessor functions.
SOS-methods-util.Rcontains a lot of convenience and accessor functions, and should be used to keep the file
SOS-methods-plotting.Rcontains plotting functions.
PrintShowStructureSummary-methods.Rcontains functions to override
summaryfunctions and the like; these may go in this file or also into the file where the respective class is defined.
Wrapper-methods.Rcontains methods and functions for the convenience wrapper functions for easier data access.
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.Rcontains 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).Rcontains tests of connections to different types of SOS and different SOS instances.
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.
gmlEnvelopeName <- "Envelope",
ogcGeometryOperandLineStringName <- "gml:LineString", or
ogcTempOpTMEqualsName <- "TM_Equals".
Data models, i.e. requests and responses, are modelled as S4 classes. Documentation can be found at the following sites (and others):
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 are implemented with
testthat. Run them with “Ctrl + Alt + T” in RStudio, with the RStudio UI via
Build → More → Test Package, or with
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.
Clone this repository.
Change to the
docker subfolder in any terminal of your choice.
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
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
Point your browser to http://localhost:8787/.
Login with Username
rstudio and Password
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
Open the sos4R project via menu
Open Project → open folder
sos4R → select
See Versions and Branches for information about the release flow. In your new feature branch, implement the feature. Add tests.
A new release shall be uploaded to CRAN after testing and under the following procedure:
devtools::check(document = FALSE)or “Build → Check” in RStudio; fix all errors, warnings, and notes
NEWS.mdfile based on latest commits, add missing changes/updates/notable things
Datefield in the
DESCRIPTIONfile to match the release date
masterand 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
develrelease of R, you can use a local Docker container to run the checks while fixing them (from the path of the parten folder of
docker run --rm -it -v $(pwd)/sos4R:/home/sos4R rocker/geospatial:devel bash, switch to
/home, then run the commands below (
R CMD build&
R CMD build sos4R; R CMD check --as-cran sos4R_<version number>.tar.gzshould have no errors, warnings, or notes
revdepcheck::revdep_check()for checking reverse dependencies
devtools::check_win_devel()for testing Windows using CRAN infrastructure
rhub::check_for_cran(email = <...>)for testing for CRAN submissions using RHub infrastructure
rhub::check(email = <...>)for running checks on different operating systems
options(rmarkdown.html_vignette.check_title = FALSE); pkgdown::build_site()and re-knit
README.Rmd, commit changes
devtools::release()(which will ask you again if you did many of the steps before)
foghorn::cran_incoming(pkg = "sos4R")
vfollowed by the version number (see above, must match
v1.2.3, and push it to the main repository
CRAN-RELEASEfor the precise commit
DESCRIPTIONto a new development version, e.g. from