We have release procedures for the following scenarios:
cBioPortal community release of code already in production Release with database migration
cBioPortal community release of code already in production
We often run code in production that is not ready yet for use by the wider cBioPortal community. We deploy to production what's in the master branch of the backend repo and the frontend repo. Often times this is not a tagged release. At some point this code should be released for the wider community. These are the steps we follow:
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
Changessection 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.
Once the frontend code is tagged, create a pull request to the backend repo where the frontend version is incremented in
<groupId>com.github.cbioportal</groupId> <artifactId>cbioportal-frontend</artifactId> <version>CHANGE_THIS_TO_THE_FRONTEND_TAG</version>
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.
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).
Release with database migration
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:
- Make sure no auto deployment is running for frontend from netlify
- Merge frontend release-x.y.z branch to frontend master
- 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.
A note on versioning
From pre-release to official release
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.
cBioPortal Software Version Numbers
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.
cBioPortal Database Version Numbers
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