Contributing to synapser
Source:CONTRIBUTING.md
This guide covers development, documentation, and release practices for the synapser R package, which wraps the Synapse Python client.
Development Setup
Prerequisites
- R (check
DESCRIPTIONfor minimum version) - Python 3.11+ (for the embedded Python client)
-
devtools,pkgdown(>= 2.2.0),stylerR packages
Configuration
Create ~/.synapseConfig for Synapse credentials:
An example config is at https://github.com/Sage-Bionetworks/synapsePythonClient/blob/develop/synapseclient/.synapseConfig.
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.
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 fromsynapseclient.Synapse -
.functionNameMappingSynapseclientModels: for methods fromsynapseclient.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:
-
Pick the dispatch object. This is the argument bound to the operations function’s first formal (
synapse_idforsynGet(),entityforsynStore()/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 -
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 onclass(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:
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
- Regenerate the documentation and curate the new pages (see Regenerating Documentation).
- Add each new reference page to the
reference:section of_pkgdown.yml. That index lists topics explicitly, either by name or withhas_keyword("ClassName"). A curated page that isn’t covered makespkgdown::build_reference()fail with “Topics missing from index”. - 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
synapseclienton first import, so re-runningload_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.
-
Build the package to regenerate
auto-man/: -
Diff the auto-generated files:
-
Manually copy new or changed files from
auto-man/toman/, editing as needed:For models listed in
.operationsUnsupportedModelMethodsinR/shared.R,tools/createRdFiles.Rautomatically generates.Rdfiles for the individual methods. DO NOT copy those method files intoman/; add their examples to the model’s constructor page instead.-
Run the
translate-rd-python-to-rskill 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 theauto-man/draft or the in-progressman/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.
Update the
_pkgdown.ymlfiles 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.-
Check if the newly generated reference page can be rendered successfully. The
overridebuilds intosite-out/, the same folder the docs workflow uses, so nothing underdocs/changes. -
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
-
Commit the
auto-man/,man/,_pkgdown.ymlandvignettes/changes. Do not commit rendered pages: the docs workflow builds and publishes the site.
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:
-
Create a release candidate branch from
develop: Update
NEWS.md(changelog) and bump the version inDESCRIPTION.-
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). -
On GitHub → Releases, draft a new release:
-
Tag:
X.Y.Z-rc -
Target:
vX.Y-rcbranch -
Title:
X.Y.Z-rc - Check “Set as a pre-release”
-
Tag:
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:
-
On GitHub → Releases, draft a new release:
-
Tag:
X.Y.Z -
Target:
vX.Y-rcbranch -
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.jsonin 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") -
Tag:
-
Merge the release candidate to
master:Pushing to
masterruns the docs workflow, which publishes thestable/docs at https://r-docs.synapse.org/stable/. -
Merge
masterback todevelop:
Publishing Documentation
Users discover synapser through several entry points:
- Synapse Docs portal: https://r-docs.synapse.org/
- GitHub repository: https://github.com/Sage-Bionetworks/synapser
- R-universe: https://sage-bionetworks.r-universe.dev/synapser
- 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 tovX.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 deletesvX.Y.Z-rc/, and merging the release candidate tomasterupdatesstable/.
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.