Skip to contents

This guide covers development, documentation, and release practices for the synapser R package, which wraps the Synapse Python client.

Repository

Branches

Branch Purpose
master Latest release
develop Active development
vX.Y.Z-rc Release candidate for version X.Y.Z

Development Setup

Prerequisites

  • R (check DESCRIPTION for minimum version)
  • Python 3.11+ (for the embedded Python client)
  • devtools, pkgdown (>= 2.2.0), styler R packages

Configuration

Create ~/.synapseConfig for Synapse credentials:

[authentication]
authtoken=your_personal_access_token

An example config is at https://github.com/Sage-Bionetworks/synapsePythonClient/blob/develop/synapseclient/.synapseConfig.

Create a Feature Branch

  1. Checkout a new branch from develop:

    git checkout develop
    git pull
    git checkout -b SYNR-1234-short-description
  2. On your branch, add these repository secrets (values in LastPass under “Python Client dev stack openssl keys”) to enable vignette integration tests in GitHub Actions:

    • encrypted_d17283647768_iv
    • encrypted_d17283647768_key

Making Changes

Code Style

Follow tidyverse style guidelines. Format files before committing:

styler::style_file("R/your_file.R")

You can also utilize Air - R Language Support extension from VS code or cursor to allow Air to format R code on save for you.

Submitting a Pull Request

Push your branch to your feature branch:

git push --set-upstream origin SYNR-1234-short-description

When your change is ready for review:

  • Open a Pull Request from your branch to develop in Sage-Bionetworks/synapser.
  • Request review from the DPE team or a designated reviewer.
  • After approval and passing checks, merge into develop.

Adding New Models or Functions

When the underlying Python client adds new model classes or top-level functions that should be exposed in synapser, update the corresponding allowlists and mappings in R/shared.R.

1. Whitelist new model classes — .modelClassesToInclude

R/shared.R contains a character vector that controls which Python model classes get wrapped as R functions:

.modelClassesToInclude <- c(
  "Agent",
  "AgentSession",
  "Project",
  "Folder",
  "File",
  # ... etc.
)

Add the exact Python class name (case-sensitive, matching synapseclient.models) to this vector. Classes omitted here will not be wrapped. Classes that are commented out are intentionally excluded.

2. Whitelist new operations functions — .operationsFunctionNames

R/shared.R also contains an allowlist for synchronous functions exposed from synapseclient.operations:

.operationsFunctionNames <- c(
  "get",
  "store",
  "delete",
  "download_list_files",
  # ... etc.
)

Add the exact Python function name (case-sensitive) to this vector when you want it wrapped into syn* R functions. Model methods with the same name are then removed from the class wrappers; see step 6 for classes the operations function doesn’t support.

3. Whitelist legacy Synapse functions — .synapseClassMethodsToInclude

Some wrappers are generated from the legacy synapseclient.Synapse class:

.synapseClassMethodsToInclude <- c(
  "login",
  "logout",
  "setEndpoints",
  "sendMessage",
  "rest_get_async",
  # ... etc.
)

4. Add function name mappings — .functionNameMappingSynapse and .functionNameMappingSynapseclientModels

By default, Python method names are converted to R function names using a syn prefix (for example, store -> synStore). Use these mapping helpers in R/shared.R when the generated name should be renamed for clarity:

  • .functionNameMappingSynapse: for methods from synapseclient.Synapse
  • .functionNameMappingSynapseclientModels: for methods from synapseclient.models

Example mappings:

.functionNameMappingSynapse <- function() {
  list(
    explicit = list(
      "synRestGetAsync" = "synRestGet",
   # ... etc.
    )
  )
}

.functionNameMappingSynapseclientModels <- function() {
  list(
    explicit = list(
      # "auto-generated R name" = "desired R name"
      "synDisassociateFromEntity" = "synDisassociateActivityFromEntity",
      "synFromPath"               = "synGetFromPath",
      # ... etc.
    )
  )
}

Add a new "auto-generated-name" = "desired-name" entry under the appropriate mapping function for any method whose default R name should be overridden.

5. Exclude specific methods — .modelClassMethodsToOmit

Methods from synapseclient.models that are internal or not useful in R (e.g., fill_from_dict, to_synapse_request) are listed in:

.modelClassMethodsToOmit <- c(
  "format_for_manifest",
  "fill_from_dict",
  "to_synapse_request",
  "allow_client_caching"
)

Add method names here to suppress them from the generated R wrappers.

6. Keep model methods the operations factory can’t dispatch — .operationsUnsupportedModelMethods

Any model method whose name is in .operationsFunctionNames (for example get, store, delete) is dropped from that class’s R wrappers, because synGet(), synStore(), and synDelete() are generated from the synapseclient.operations functions instead. That only works if the operations function supports the class. For classes it doesn’t support, store() and delete() raise an error such as Unsupported entity type: Submission, while get() treats the unsupported instance as a Synapse ID, so the call fails later, in the entity lookup. Either way, the model’s own method would otherwise be unreachable from R.

To keep a model’s own method, add the class and method names to .operationsUnsupportedModelMethods in R/shared.R:

.operationsUnsupportedModelMethods <- list(
  WikiPage = c("get", "store", "delete"),
  Submission = c("get", "store", "delete"),
  Evaluation = c("get"),
  Activity = c("store", "delete"),
  # ... etc.
)

Methods listed here stay wrapped, and .defineOperationsFallbacks() in R/zzz.R replaces synGet()/synStore()/synDelete() with a shim. The shim decides whether a call goes to the model’s own method (e.g. Activity$store) or to the synapseclient.operations function, which only accepts entities. For example, Activity(...) |> synStore(parent = file) reaches Activity.store, and Submission(id = "9999999") |> synGet() reaches Submission.get. Anything without a listed method falls back to the operations function.

The shim decides in two steps:

  1. Pick the dispatch object. This is the argument bound to the operations function’s first formal (synapse_id for synGet(), entity for synStore()/synDelete()): that argument by name if the caller supplied it, otherwise the first unnamed argument. It is not simply the first argument by position. Named arguments can come in any order, so the object may not be first:

    synStore(parent = file, entity = activity)   # dispatches on `activity`
    synStore(parent = file, activity)            # dispatches on `activity`
    synGet(synapse_id = Submission(id = "9"))    # dispatches on the Submission
  2. Match its class. The shim strips the module path from each entry of class(<object>) and uses the first one that has a worker in .functionalMethodDispatch. Matching on class(x)[1] as-is is not enough, because only objects built with an R constructor carry the short class name. An object read from a field or a list carries reticulate’s full dotted path:

    activity <- Activity(name = "x")
    file <- File(id = "syn123", activity = activity)  # an existing file you can edit
    
    class(activity)[1]       # "Activity"
    class(file$activity)[1]  # "synapseclient.models.activity.Activity"
    
    synStore(file$activity, parent = file)   # reaches Activity.store

To check whether a class needs an entry, look for it in the supported types of the matching operations function in synapseclient/operations/ (store_operations.py, factory_operations.py, delete_operations.py). Remove the entry once the operations function supports the class. For documentation, tools/createRdFiles.R still generates auto-man/ pages for these methods, but they are not copied into man/; put their examples on the model’s constructor page instead (see Regenerating Documentation).

7. Whitelist operations option classes — .operationsClassesToInclude

Option dataclasses from synapseclient.operations that callers construct directly, to configure synGet()/synStore() calls or to pass as arguments, are listed in:

.operationsClassesToInclude <- c(
  "StoreFileOptions",
  "FileOptions",
  "TableOptions",
  "DownloadListItem",
  # ... etc.
)

Add the exact Python class name here when a new option class is introduced; otherwise R users have no constructor for it. A class that is referenced in an argument but not exposed (for example a csv_table_descriptor argument whose class is not listed here) can only be left as NULL from R.

After updating the allowlists

  1. Regenerate the documentation and curate the new pages (see Regenerating Documentation).
  2. Add each new reference page to the reference: section of _pkgdown.yml. That index lists topics explicitly, either by name or with has_keyword("ClassName"). A curated page that isn’t covered makes pkgdown::build_reference() fail with “Topics missing from index”.
  3. In a fresh R session, confirm the new wrapper exists and dispatches as expected, e.g. exists("synNewFunction") and a call on an instance of the class.

Updating the Python Client Version

The wrapped Python client version is pinned in R/shared.R:

PYTHON_CLIENT_VERSION <- "4.14"

After bumping the version, update the Python range in SystemRequirements in DESCRIPTION to match the release’s Requires-Python, then regenerate documentation (see next section).

Testing Against a synapseclient Feature Branch

To exercise synapser against unreleased changes on a synapsePythonClient feature branch, put your checkout on PYTHONPATH in a fresh R session before loading synapser:

Sys.setenv(PYTHONPATH = "/path/to/synapsePythonClient")
devtools::load_all("/path/to/synapser")

synapser still provisions its uv-managed environment with the pinned synapseclient[pandas], which supplies the dependencies. Python searches PYTHONPATH before site-packages, so import synapseclient resolves to your checkout, including uncommitted edits.

  • If the branch adds a Python dependency the pinned version lacks, declare it before loading, e.g. reticulate::py_require("newdep").
  • If you edit the synapsePythonClient checkout after synapser has loaded, restart R to pick up the edits. Python caches synapseclient on first import, so re-running load_all() in the same session reuses the old code.
  • The same allowlist check as for a version bump applies (see Updating the Python Client Version).

To confirm synapser loaded your branch:

reticulate::py_run_string("import synapseclient; print(synapseclient.__version__))")

The printed file path should point into your feature-branch checkout, and the version is the checkout’s, not PYTHON_CLIENT_VERSION.

Python Environment

synapser runs in its own ephemeral Python environment, which reticulate automatically sets up using uv and the pinned version of synapseclient[pandas] (see R/shared.R). No manual Python installation or environment setup is required.

If Python has not yet been initialized, synapser ignores RETICULATE_PYTHON, use_python(), activated virtual environments, and project-level .venv directories.

Note: Python can only be set up once per R session. If another package initializes Python before synapser loads, synapser stops with an error naming the Python it found. Restart R and load synapser first.

To confirm which environment synapser is using:

reticulate::py_config()  # the python: path should be under reticulate's uv cache
reticulate::py_run_string("import synapseclient; print(synapseclient.__version__)")

Regenerating Documentation

synapser auto-generates draft .Rd files from Python docstrings into auto-man/. These must be manually reviewed and merged into man/ before committing.

  1. Build the package to regenerate auto-man/:

    R CMD INSTALL .
  2. Diff the auto-generated files:

    git diff auto-man/
  3. Manually copy new or changed files from auto-man/ to man/, editing as needed:

    • For models listed in .operationsUnsupportedModelMethods in R/shared.R, tools/createRdFiles.R automatically generates .Rd files for the individual methods. DO NOT copy those method files into man/; add their examples to the model’s constructor page instead.

    • Run the translate-rd-python-to-r skill for a first-pass edit: it converts Python terms/syntax in \description{}, \arguments{}, and \value{} to R-friendly wording, and translates the Python code in \examples{} to R.

      • In Claude Code, from the repo root (so .claude/skills/ is discovered), invoke it as a slash command against the file(s) to curate — one or several, either the auto-man/ draft or the in-progress man/ copy:

        /translate-rd-python-to-r man/
        /translate-rd-python-to-r man/file_name.Rd
      • It verifies names/behavior against the real R API and the Python source in synapsePythonClient, and checks each Rd tag’s formatting (title, empty sections, \arguments{} vs. \usage{}, brace balance in \examples{}) — but leaves anything it can’t verify for the developer to resolve manually.

    • Review the skill’s output (and anything it flagged or left untouched): confirm parameter descriptions and translated code are accurate for R callers before committing.

  4. Update the _pkgdown.yml files to reflect any new or modified content. Be sure to organize tutorials imported from the Python client under the “Tutorials” section, and place supplementary materials or extended examples in the “Advanced” section under “Further Reading,” as appropriate.

  5. Check if the newly generated reference page can be rendered successfully. The override builds into site-out/, the same folder the docs workflow uses, so nothing under docs/ changes.

    R -e "pkgdown::build_reference(override = list(destination = 'site-out'))"
  6. Check if newly generated home or article pages can be rendered successfully. For guidance on additional documentation sections, refer to: https://pkgdown.r-lib.org/reference/index.html

    R -e "pkgdown::build_home(override = list(destination = 'site-out'))"
    R -e "pkgdown::build_articles(override = list(destination = 'site-out'))"
  7. Commit the auto-man/, man/, _pkgdown.yml and vignettes/ changes. Do not commit rendered pages: the docs workflow builds and publishes the site.

    git add auto-man/ man/ _pkgdown.yml vignettes/
    git commit -m "SYNR-1234: update generated and curated docs for new FooClass wrapper"

Note: Do not skip the manual review step — Python docstrings often contain Python-specific syntax that renders incorrectly in R documentation.

Release Process

Step 1: Identify scope

Review open SYNR JIRA tickets, set the target version, and assign tickets. All feature work merges to develop via Pull Requests (see above).

Step 2: Staging release

Once all tickets for the release are resolved:

  1. Create a release candidate branch from develop:

    git checkout -b vX.Y-rc develop
  2. Update NEWS.md (changelog) and bump the version in DESCRIPTION.

  3. Rebuild the README and check that the pkgdown site builds:

    R -e "devtools::build_readme()"
    R -e "pkgdown::build_site(override = list(destination = 'site-out'))"

    Review site-out/index.html, then commit and push. The rendered site is not committed: the docs workflow builds and publishes it (see Publishing Documentation).

  4. On GitHub → Releases, draft a new release:

    • Tag: X.Y.Z-rc
    • Target: vX.Y-rc branch
    • Title: X.Y.Z-rc
    • Check “Set as a pre-release”
  5. Notify validators with the release candidate tag (e.g. 3.1.0-rc).

Step 3: Validation

Validators install the release candidate from its GitHub tag:

remotes::install_github("Sage-Bionetworks/synapser@X.Y.Z-rc")

A pre-release is not deployed to R-universe, which builds only the latest full release. Publishing the pre-release publishes the docs for this release candidate to vX.Y.Z-rc/ on the docs site, so validators can review them (see Publishing Documentation).

Step 4: Patch staging (if needed)

For critical bugs found during validation: 1. Fix on a branch off vX.Y-rc, open a PR back to vX.Y-rc. 2. After merge, move the X.Y.Z-rc pre-release to the new commit (delete and re-create the pre-release and its tag), so the docs in vX.Y.Z-rc/ are rebuilt, then repeat Step 2 step 5 in staging release section. 3. Notify validators to re-test and re-validate the ticket with the updated release candidate.

Step 5: Production release

Once all tickets are closed:

  1. On GitHub → Releases, draft a new release:

    • Tag: X.Y.Z
    • Target: vX.Y-rc branch
    • Title: X.Y.Z
    • Do NOT check “This is a pre-release”

    Publishing the release is what deploys it: R-universe tracks the latest GitHub release of synapser, picks up the new tag, and builds source and binary packages for Windows, macOS, and Linux. R-universe checks package repositories and the registry for changes every hour, so the build can take up to an hour to start. To start the build sooner, trigger a sync manually with the sync button on the R-universe packages page.

    R-universe builds the new release only if the synapser entry in packages.json in the registry repository, Sage-Bionetworks/Sage-Bionetworks.r-universe.dev, has "branch": "*release", which looks up the most recent GitHub release. With any other value, R-universe builds that branch instead. Check this before publishing the release. Currently, the branch is set to be “*release”.

    Check the build status on the R-universe builds page, then confirm the new version installs:

    install.packages(
      "synapser",
      repos = c("https://sage-bionetworks.r-universe.dev", "https://cloud.r-project.org")
    )
    packageVersion("synapser")
  2. Merge the release candidate to master:

    git checkout master
    git merge vX.Y-rc
    git push upstream master

    Pushing to master runs the docs workflow, which publishes the stable/ docs at https://r-docs.synapse.org/stable/.

  3. Merge master back to develop:

    git checkout develop
    git merge master
    git push upstream develop

Publishing Documentation

Users discover synapser through several entry points:

  1. Synapse Docs portal: https://r-docs.synapse.org/
  2. GitHub repository: https://github.com/Sage-Bionetworks/synapser
  3. R-universe: https://sage-bionetworks.r-universe.dev/synapser
  4. Synapse R repository (RAN), for synapser 2.x and earlier only: http://ran.synapse.org

Each location should include general synapser information and installation guidance. The package documentation site should be the canonical source for full documentation, and the other locations should link to it.

The docs site is built and published automatically by the docs GitHub Actions workflow (.github/workflows/docs.yml), so rendered pages are not committed to this repository. Each build owns one folder on the gh-pages branch, which GitHub Pages serves:

Event Published to
Push to develop latest/
Push to master stable/
Production release, tag X.Y.Z vX.Y.Z/
Pre-release, tag X.Y.Z-rc vX.Y.Z-rc/, deleted once X.Y.Z is published

Other pre-release tags (for example X.Y.Z-test or X.Y.Z-rc1) are not published, and neither are pushes to a vX.Y-rc branch. The site root forwards to stable/ (or to latest/ until there is a stable version), and the home page of every version has a version picker. The list of versions is versions.json at the site root; .github/scripts/docs_versions.py rewrites it on every publish.

Documentation updates are part of the release process:

  • During a staging release, check that the site builds locally (see Step 2). Publishing the pre-release (tag X.Y.Z-rc) adds its docs to vX.Y.Z-rc/; pushes to the release candidate branch are not published.
  • During a production release, publishing the release (tag X.Y.Z) adds that version’s docs and deletes vX.Y.Z-rc/, and merging the release candidate to master updates stable/.

CI/CD

GitHub Actions build and test every change. The build workflow is defined in .github/workflows/build.yml. Package deployment is handled outside this repository’s workflows: R-universe builds and serves each full GitHub release (see Step 5). The documentation site is built and published by .github/workflows/docs.yml (see Publishing Documentation). Every push to a fork runs the build and test suite automatically.