CONTRIBUTING.md

In vegawidget/altair: Interface to 'Altair'

Contributing

Package scope

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

• to install the Altair Python package.
• to build Vega-Lite chart-specifications using Altair.
• to render chart-specifications into HTML.
• to communicate your charts.

There are a lot of “moving parts” in keeping current with a Python package and a set of JavaScript libraries (Vega-Lite, vega-embed, …). Accordingly, this package aspires to keep its scope as focused as possible.

Style

Looking at the present state of this package repository, you may think that this style guide is more aspirational than operational. You would not be incorrect in this assessment.

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.

  ``` r

  ' @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.

In documentation, we reserve the use of “capital-A” Altair to refer to the Python package, and the use of “small-a” to refer to this package.

Although we are mimicking calls to Python code, even copying-and-pasting Python examples, we should make the syntax of the calls as R-like as possible. Consider this Python example from Altair:

import altair as alt
from vega_datasets import data
cars = data.cars()

chart = alt.Chart(cars).mark_point().encode(
    x='Horsepower',
    y='Miles_per_Gallon',
    color='Origin',
    shape='Origin'
)

And how we would write this in R:

library("altair")

vega_data <- import_vega_data()
cars <- vega_data$cars()

chart <-
  alt$Chart(cars)$
  mark_point()$
  encode(
    x = "Horsepower",
    y = "Miles_per_Gallon",
    color = "Origin",
    shape = "Origin"
  )

This formatting-style is an experiment. Clearly, the $ operator is not a pipe, %>%. However, it can be used across line-breaks such that we could format the code in the same style as a pipe. This may not be completely satisfying, but it at least resembles a ggplot2 style.

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”.

Versioning

The version number may have as many as four components. The first two digits will mirror the first two digits of the version number of the supported (Python) Altair version; this is currently 3.1.0.

The third component will correspond to a CRAN release of this package; these will be tagged.

A fourth component denotes a development version.

Our goal is that each commit to the master branch will have an incremented version-number.

Pull requests

Pull requests are very welcome. Accordingly, the branch into 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 a vignette | master | ✅ | 😁 | | helping with a new feature | <feature-branch> | ❎ | 😁 | | proposing a new feature | master | ✅ | 😁 |

Please roxygenize as a part of your pull-request.

Git branch strategy

One of the motivations is to make our lives as developers, and as users, easier by restricting what types of Altair versions will be supported on which types of git branches.

We should first define “type of Altair version” and “supported”.

There are three types of Altair versions:

• released refers to a released version available on Conda-Forge
• candidate refers to a release-candidate available on PyPi
• github refers to a development version available at GitHub

We define “supported” as making the version available through the install_altair() function and hardcoding this Altair version as getOption("altair.python.version.supported").

• master: only released versions shall be supported on the master branch.

• <feature-branch>: any type of version may be supported on a <feature-branch>. However, to merge into master, it must support a released or candidate version.

vegawidget/altair documentation built on Feb. 3, 2024, 7:47 p.m.