Page Comparison

This document attempts to cover development and release practices for the synapser projects. As of synapser 1.0.0+, PythonEmbedInR is no longer used.

...

References:

• 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()

...

1. Create a new release candidate branch from develop with branch name as the version to release (v1.0-rc)

2. Update the docs in the release candidate branch:

   1. 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)

   2. Update the changelog contained in NEWS.md

   3. Update the version in the DESCRIPTION file, as the version is reflected in the generated documentation.

   4. from the repo directory run the following command:

      Code Block
      R -e "pkgdown::build_site()"

   5. Review the changes by inspecting docs/index.html file.

   6. Commit the changes to the docs directory. When this release branch is validated and merged to master it will automatically publish to https://r-docs.synapse.org via GitHub Pages.

3. Create a new staging release

   1. Go to the releases of the appropriate repo https://github.com/Sage-Bionetworks/synapser/releases

   2. Click the "Draft a new release" button and fill the following values:
      
      Important: Check the "This is a pre-release" checkbox. This will cause the release to be deployed to test.pypi.org rather than production pypi.org.
      
      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)

   3. Hit the publish button, this will trigger a GitHub Action that will test and deploy the production release to http://staging-ran.synapse.org/

4. 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).

...

1. Go to the releases of the appropriate repo https://github.com/Sage-Bionetworks/synapser/releases

2. Click the "Draft a new release" button and fill the following values:
   
   Tag version: X.Y where X.Y is the release version (e.g. 0.11)
   Target: the previously created vX.Y-rc branch
   Release title: Same as tag version (X.Y)
   
   Do NOT check the "This is a pre-release" checkbox.
   
   

3. Hit the publish button, this will trigger a GitHub Action that will test and deploy the production release to http://ran.synapse.org/

4. Merge the develop branch to the master branch.

...

• Synapse portal > docs site at (1) http://docs.synapse.org/r/

• Github repo at (2) https://github.com/Sage-Bionetworks/synapser  and its site at (3) https://Sage-Bionetworks.github.io/synapser/

• Sage RAN including staging RAN at (4) http://staging-ran.synapse.org and production RAN at (5) http://ran.synapse.org

...

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

MacOS runner

Currently the builds utilize one external self hosted runner for Mac builds (Linux and Windows builds are run on ephemeral GitHub hosted runners). This is due to GitHub Actions currently only supporting Catalina based GitHub hosted runners, whereas the build uses a Mojave based runner in order to ensure better binary compatibility when installed on older versions of MacOS.

The current self hosted runner is a MacStadium machine which Sage subscribes to. The IP address and credential are available in LastPass. You can log into either via SSH or using VNC.

If the instance ever needs to be recreated, it can be set up on a new machine as follows:

...

Install R:

1. Install each version needed (as listed in the build.yml workflows) using pkg installer from the R Mac install page.

2. After installing each version run the following command:

   Code Block
   language bash
   pkgutil --pkgs | grep -i org.r-project | xargs -I {} sudo pkgutil --forget {}

   Normally installing a version from the package installer will uninstall a previous version. "Forgetting" the previously installed version allows multiple versions to be installed at the same time.

If they haven't already been installed, install X-code command line tools

xcode-select --install

...

# https://stackoverflow.com/a/58349403

for HEADER_PATH in /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/*
do
	INCLUDE_PATH="/usr/local/include/$(basename $HEADER_PATH)"
	if [ ! -f $INCLUDE_PATH ]; then
		sudo ln -s $HEADER_PATH $INCLUDE_PATH
	fi
done

Install brew https://brew.sh/ if it is not already installed. From brew, install pandoc:

brew install pandoc

...

For EACH the PythonEmbedInR and synapser GitHub repos, add a self-hosted runner by doing the following:

1. Got to the GitHub action runner settings for the repo:

   1. https://github.com/Sage-Bionetworks/PythonEmbedInR/settings/actions/runners

   2. https://github.com/Sage-Bionetworks/synapser/settings/actions/runners

2. If a previous runner being replaced is listed remove it.

3. Follow the instructions to add a new runner, giving it a unique label that matches the label used in the workflow build.yml, e.g. "macos-mojave".

4. Follow the GitHub instructions on the runner dialog for enabling the runner script as a service.

References:

...

References:

• R package docs site tools: https://pkgdown.r-lib.org/

• Github Pages instructions: https://helpdocs.github.com/articles/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages/-site