Contributing

Package scope

The purpose of this package is to provide you the means:

• to build Vega-Lite chart-specifications.
• to render chart-specifications into HTML.
• to communicate your charts.

Style

This package aspires to use the Tidyverse Style Guide, with some minor modifications.

• Documenting parameters:

  For @param and @return, the text should starting with the expected class (or possible classes) of the argument or return value, followed by a comma, then the (uncapitalized) description. If omitting the class name, then begin the description with a capital letter.

  #' @param spec  An object to be coerced to `vegaspec`, a Vega/Vega-Lite specification
  #' @param width `integer`, sets the view width in pixels
  #'
  #' @return `logical` indicating success

In the documentation, we use specification or spec to describe the JSON or the list; we use chart to describe the rendering, the finished product. These seem to be the terms-of-art that Vega-Lite uses.

Development strategy

So that we can use the (very useful) pull-request functions from usethis, we follow the Tidyverse convention of using the master branch as the reference branch for pull-requests. However, you should not make a pull-request from your copy of the master branch; you should work from a branch named for the change you are proposing. For more information, please see the usethis pull-request reference.

We will wish for master to contain only stable versions. We will not normally merge a pull-request that does not pass the CI checks. Further, we will intend that each commit to master will have a incremented version number; we will manage this as a part of the pull-request process.

Please build pkgdown as much as you would like - the docs folder is git-ignored; the pkgdown site is built and deployed automatically upon update of the GitHub master branch. The CRAN version of the documentation is at the “root” of the documentation site; the latest master version will be deployed to the dev directory of the “root”.

Pull requests

Pull requests are very welcome. The branch to which you should make a pull-request will depend on the situation:

Situation	Reference branch	Add item to NEWS.md	Appreciated
bug-fix	master	✅	😁
improving documentation	master	❎	😁
adding vignette	master	✅	😁
helping with a new feature	<feature-branch>	❎	😁
proposing a new feature	master	✅	😁

Please roxygenize as a part of your pull-request. Let’s all do our best to keep to the current CRAN version of roxygen2.

Versioning

The first digit indicates the maturity of this package’s API. For the time being, it will be 0.

The second digit will be incremented upon each CRAN release and assigned a GitHub release tag.

Vega versions

To update the JavaScript files for Vega, Vega-Lite, and vega-embed, a maintainer will render the R markdown document found at data-raw/infrastructure.Rmd. The key parameter to adjust is vega_lite_version, in the YAML header:

---
title: Package infrastrucure
output: github_document
params:
  vega_lite_version: "3.2.1"
---

The code in the .Rmd file will determine the versions of Vega and vega-embed that are concurrent with this version of Vega-Lite.

When updating the Vega libraries for this package, please keep in mind that you may also have to:

• rebuild & reinstall your new version of this package
• rebuild the datasets (next section)
• rebuild some of the test specs and reference images, found in tests/spec and tests/reference

One day, this will be better automated.

Datasets

The sample specifications and datasets are build using the R markdown document found at data-raw/infrastructure.Rmd.

Development philosophy

S3 class system

In R, a vegaspec lives as a list, but can be imported from or exported to JSON text. Because a vegaspec is a list, we add S3 classes on top of list.

For example:

library("vegawidget")
class(spec_mtcars)

## [1] "vegaspec_unit"      "vegaspec_vega_lite" "vegaspec"          
## [4] "list"

We see that in addition to list we have classes for:

• vegaspec: to include all Vega and Vega-Lite specification
• vegaspec_vega_lite: denotes that this is a Vega-Lite specification
• vegaspec_unit: denotes that this is a unit specification

This last (or top) class is used to distinguish different compositions of Vega-Lite specifications. In this case, a unit-specification is one that is a single non-layered view.

The possible classes are: vegaspec_unit, vegaspec_layer, vegaspec_facet, vegaspec_repeat, vegaspec_concat, vegaspec_hconcat, vegaspec_vconcat.

For Vega specifications, the situation is simpler:

class(vw_to_vega(spec_mtcars))

## [1] "vegaspec_vega" "vegaspec"      "list"