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 vingettes manually you can use
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.
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.Rcontains tests of connections to different types of SOS and different SOS instances.
packaging.Rcontains the functions for creating package documentation and should be used as the spot to collect useful functions and workflows around future documentation and the packaging process.
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):
Tests are implemented with
testthat. Run them with
or by clicking the “Check” button in RStudio (which does more than just running the tests!).
In the docker folder, a Dockerfile is provided that can be used to set-up an isolated container just for sos4R development. This includes all required dependencies, RStudio as webapplication, and devtools. The current size of the image is ~4.02GB.
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
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)and fix errors, warnings, and notes
Datefield in the
DESCRIPTIONfile to match the release date
masterand check the CI status, fix all problems
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
README.Rmd, commit changes
masterbranch -_ Do the actual release_ with
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
DESCRIPTIONto a new development version, e.g. from
You can then do the actual release with
When available on CRAN: