# Release Procedure

We have release procedures for the following scenarios:

1. cBioPortal community release of code already in production
2. Release with database migration

We often run code in production that is not ready yet for use by the wider cBioPortal community. The frontend gets deployed to production after every merge to master. The backend gets updated every Tuesday before our community call (occasionally more frequently too if issues are identified). We tag whatever is in the master and frontend repo and put a "Pre-Release" indication on it. After a month of stable usage in production, one of the tags will get the "latest" indication on the GitHub. These are the steps we follow to create a release:

1. Create a new frontend tag. The releases can be found here: https://github.com/cBioPortal/cbioportal-frontend/releases. A draft of the release notes are automatically generated by https://github.com/marketplace/actions/release-drafter. If there are pull requests in the Changes section i.e. they have not been labeled with one of the labels defined here. Try to label them and trigger a rerun by committing something to the master branch. Alternatively you can manually put them in a particular section. Note that our goal is to have automated release notes, so it would be great if you could send a PR to update the release-drafter.yml in case you find certain PRs don't fit in a particular section or a section should be altered. Look at other release notes for inspiration: https://github.com/cBioPortal/cbioportal-frontend/releases. You can save your work as a draft if necessary.

2. Once the frontend code is tagged, create a pull request to the backend repo where the frontend version is incremented in portal/pom.xml:

      <groupId>com.github.cbioportal</groupId>
      <artifactId>cbioportal-frontend</artifactId>
      <version>CHANGE_THIS_TO_THE_FRONTEND_TAG</version>

3. Once that PR is merged, one can create a tag for the backend repo with the same tag as the frontend repo. You should see a draft from release drafter similar to the frontend in the backend repo: https://github.com/cBioPortal/cbioportal/releases. The idea is to create one set of release notes in the backend repo that is a combination of the frontend and backend notes. To make the hyperlinks from the frontend repo work in the backend repo you can copy the frontend release notes raw markdown and run the following one liner to convert the links:

   pbpaste | sed 's|(#\(....\)|([cbioportal-frontend#\1](https://github.com/cBioPortal/cbioportal-frontend/pull/\1)|g'

   then put them in the right sections following same style as other releases: https://github.com/cBioPortal/cbioportal-frontend/releases.

4. Create a news item with a link to your carefully crafted release notes. Highlight a few major changes that could be interesting to users of cBioPortal ideally with a screenshot similar to: https://github.com/cBioPortal/cbioportal/pull/6914/files?short\_path=6f95322#diff-6f953229832059bab3fe229d4af08b52 (in the files changed section, you can click on view rich diff to see the converted markdown).

Occasionally there are bugs identified in the backend running in production. Creating an entire new release can be cumbersome so in this case, we create a new release branch instead. E.g. if the current release is 6.0.2, the new branch would be release-6.0.3. Any fixes are then merged to this branch and if it looks good, they are deployed to production. On the following Tuesday whatever's in this release-x branch get merged to master and included in that Tuesday's release.

For releases with database migrations, we increase the MINOR number in MAJOR.MINOR.PATCH. For those releases we have a separate branch (see https://github.com/cBioPortal/cbioportal/blob/master/CONTRIBUTING.md#branches-within-cbioportal), which needs to be merged to master on both backend and frontend:

1. Make sure no auto deployment is running for frontend from netlify
2. Merge frontend release-x.y.z branch to frontend master
3. Follow same procedure as for a PATCH release, but instead of having a separate PR to update the frontend (step 2) one can add it to the already existing backend branch release-x.y.z and open the PR from there to backend's master. This is merely for convenience to avoid having to create another branch just to update the frontend version.

On the GitHub Release Page you will see that some releases have the pre-release indication whereas others do not. In general we make a new pre-release release every week. We test it out in production (https://cbioportal.org) for one month and if no new critical issues are identified we make it an official release. Occasionally we make a new official release in less than a month's time if we identify a critical issue in the previous release.

We follow the following logic when deciding how/when to increment the version of cBioPortal. It's a complete modification of semantic versioning (MAJOR.MINOR.PATCH) more suitable for our purposes:

MAJOR : A big change in how cBioPortal works. We changed the major version from 1 to 2 when we completely moved from using JSPs to a Single Page App written in React calling a REST service. Another example: we changed from 2 to 3 when we made session-service a requirement.

MINOR : Changes that require a database migration, an upgrade to another cBioPortal component (e.g. session-service) or anything that could require additional effort for a deployer of cBioPortal (e.g. see transcript change).

PATCH : Changes that don't require database migrations. Could be new features as well as bug fixes to either frontend, backend or both.

See also: https://github.com/cBioPortal/cbioportal/releases

cBioPortal database version numbers are different version numbers than the software version numbers, it's only updated when developers make database scheme changes, please see cBioPortal Database Versioning

The following is a provisional system of alerting user to new features and announcements. It would probably be better for these messages to be configurable on an instance level by installers. For now, the following suffices.

Top banner: see sample configuration in src/shared/components/userMessager/UserMessage.tsx

For a beacon and associated dialog message, use this as a model, where child of InfoBeacon component is any component that will be shown when InfoBeacon is moused over and conditions are met

<If condition={!isWebdriver()}>
  <InfoBeacon
      top={-15}
      right={45}
      interaction={'mouseover'}
      color={'green'}
      id={'groupComparison1'}
 >
 <WrappedTour/>
 </InfoBeacon>
</If>