This document attempts to cover development and release practices for the synapser projects and synapserutils projects. As of synapser 1.0.0+, PythonEmbedInR is no longer used.
...
Table of Contents | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
|
Github repositories
The code base for Synapse R client (wrap Python client) can be found at https://github.com/Sage-Bionetworks/synapser .
Branches
master: tracking latest release
develop: tracking latest development work
release candidate branches: for each release, a new release candidate branch will be created with name set to the version to release (v1.0-rc).
...
Development and Release
Releasing a new version of synapser is a process that involves client engineers, product manager, validators, and end users.
Step 1: Identifying the next release
This step starts with client engineers and product manager going over R JIRA tickets and determining their priority, tagging them with the new release version, and assigning them to client engineers.
Step 2: Development
Develop work will be checked into develop branch.
...
Commit Best Practices: http://r-pkgs.had.co.nz/git.html#commit-best-practices
Git Branch: http://r-pkgs.had.co.nz/git.html#git-branch
Style: tidyverse style guidelines
Run
Code Block styler::style_file()
Configuration
Add this file to your home directory, uncommenting headers and fields as necessary. Heres an example:https://github.com/Sage-Bionetworks/synapsePythonClient/blob/develop/synapseclient/.synapseConfig
Changing The Version of the Underlying Python Client
The synapser package 'wraps' a specific version of the Synapse Python Client, specified in R/zzz.R
, and tools/installPythonClient.R
for example:
...
Info |
---|
Note: Make sure to add in new Rd files. |
Step 3: Deploy Staging
Once all JIRA tickets for the new release version are RESOLVED, we are ready to deploy staging version for validation process.
Create a new release candidate branch from develop with branch name as the version to release (v1.0-rc)
Update the docs in the release candidate branch:
ensure you have the R pkgdown package installed (on a Mac you may need to brew install harfbuzz, fribidi, and pandoc if you haven't already)
Update the changelog contained in
NEWS.md
Update the version in the
DESCRIPTION
file, as the version is reflected in the generated documentation.from the repo directory run the following command:
Code Block R -e "pkgdown::build_site()"
Review the changes by inspecting docs/index.html file.
Commit the changes to the docs directory and push to the release candicate branch
Create a new staging release
Go to the releases of the appropriate repo https://github.com/Sage-Bionetworks/synapser/releases
Click the "Draft a new release" button and fill the following values:
Tag version: X.Y-rc where X.Y where X.Y is the release version (e.g. 0.11-rc)
Target: the previously created vX.Y-rc branch
Release title: Same as tag version (X.Y-rc)
Important: Check the "Set as a pre-release" checkbox. This will cause the release to be deployed to a staging ran.Use the GitHub release “Generate release notes” feature to create release notes. Copy related content from the NEWS.md to the top of the release notes.
Hit the “Publish release“ button, this will trigger a GitHub Action that will test and deploy the staging release to http://staging-ran.synapse.org/
Notify validators about the available version. The validation version will be in format <version-to-build>.<build-number> (For example: 1.0.87, for build number 87).
Step 4: Validation
Validators can download and/or install the new pre-release version via install.packages() (recommended) or using devtools (not-recommended). After installing the pre-release version, a validator can validate the JIRA tickets that they were assigned and change their status to
Status | ||||
---|---|---|---|---|
|
Status | ||||
---|---|---|---|---|
|
Option 1: Installing from Staging RAN
Staging RAN Repo: http://staging-ran.synapse.org
staging-ran
Code Block | ||
---|---|---|
| ||
install.packages("synapser", repos=c("http://staging-ran.synapse.org")) |
Option 2: Using devtools
devtools-staging
Code Block | ||
---|---|---|
| ||
# replace version with the new release version devtools::install_github("Sage-Bionetworks/synapser@v1.0-rc") |
Step 5: Patch Staging
When a critical bug is found during validation, and it needed to be addressed before releasing, a patch need to go into "staging" without changing the <major>.<minor> release version.
A client engineer fix a bug, run private build, and create Pull Request to the release branch (v1.0-rc)
After the Pull Request is merged, start the staging build to update the artifacts. Please see Step 3 to recreate a staging build.
Notify the validator to re-validate the ticket with the new artifact.
Step 6: Release
After all JIRA issue are CLOSED, the new version is ready to be released. Creating a production deployment is similar to the staging deployment and is accomplished by publishing a GitHub release:
...
Code Block |
---|
git checkout develop git merge master git push upstream develop |
Step 7: Users install the released version
Option 1: Installing from RAN
RAN Repo: http://ran.synapse.org
ran
Code Block | ||
---|---|---|
| ||
install.packages("synapser", repos=c("http://ran.synapse.org")) |
Option 2: Using devtools
devtools-prod
Code Block | ||
---|---|---|
| ||
# replace version with the new released version remotes::install_github("Sage-Bionetworks/synapser@v1.0") |
...
Publishing Documentation
Users come to the synapser package through:
...
While building artifacts and pushing them to staging ran, we will generate docs and merge back to release candidate branch.
When we release the artifact to prod ran, we merge release candidate branch to master. This will update the docs site.
CI/CD configuration
As discussed above, the CI/CD for synapser is driven through GitHub Actions. The build is contained in the contained build.yml
workflows of the respective repositories (synapser).
...