This article is being authored to help developers understand current best practices for releasing new versions of your RingCentral applications and integrations which operate using the Connect Platform.
The following properties are immutable once your application has been approved for production access:
- Application Type
- Platform Type
- Authorization Flow
- API Permissions Required
- OAuth Redirect URL[s]
Knowing this means that any new version releases of your application which require modification of the above properties of your RingCentral application/integration should be considered "breaking changes" according to semantic versioning.
We do have a feature improvement issue in the Developer Portal backlog to add full application versioning support, but until such time as we have prioritized development of this feature, the current best practice for application versioning is to implement semantic versioning into the name of the application and merely include the MAJOR version number in the application name.
Current Application Version Definition Best Practices
1. Create a new application and include the MAJOR semantic versioning in the name of the app.
Example Name for a GA application/integration: MyCompanyApp_v1.x.x
2. Develop application to suit your business objectives
3. Ensure application meets graduation requirements as defined in Status & Review section for your application
4. Apply for Production
5. Release initial version of application to Production
Since only MAJOR semantic versioning numbers are considered breaking changes, developers can piggy-back non-breaking changes onto this major number and simply use their preferred Source Code Management (SCM) system to manage MINOR and PATCH package releases.
Example Use Case for a BETA Application which has been Approved for Production
If your initial application version name is a beta release: MyCompanyApp_v0.X.X
Subsequent, non-breaking changes (MINOR or PATCH) to the BETA (0.X.X) application code base can simply leverage existing RingCentral API Keys used in your Production-Approved Application.
But let's say you're ready to release version 1.0.0 of your MyCompanyApp which includes breaking changes from your beta version. This means it is time to create a new application definition in the Developer Portal. So you would follow the Current Application Version Definition Best Practices from above to define your new application's GA version.
The new application version name would be: MyCompanyApp_v1.X.X
Within this new GA version of your source code, you are able to modify all the necessary properties of your application definition which become immutable once released to production (as indicated at the beginning of this article).