SDK Versioning and Updates

Files.com SDKs use semantic versioning and ship new releases continuously. Files.com itself uses several of its own SDKs internally, so each release is exercised in production before it reaches you.

Files.com SDK Versioning

Files.com SDKs follow a three-part semantic versioning system in the form of MAJOR.MINOR.BUILDNUMBER, producing version numbers such as 1.4.221 or 1.3.0.

MAJOR or MINOR changes may introduce breaking changes. Any time a new version has a different MAJOR or MINOR number than the one you have deployed, review the changes before upgrading. Changes to the BUILDNUMBER reflect bug fixes, performance improvements, or new functionality that does not introduce breaking changes. Updating the SDK when only the BUILDNUMBER has changed is generally not disruptive.

Use the Most Current SDK Version

Use the most current version of the Files.com SDK in your projects. When you contact our support team for help with your code, this is always the first suggested troubleshooting step, because improvements and fixes to the SDKs are released continuously.

Identifying Differences Between SDK Versions

Each SDK is released on GitHub along with the appropriate package managers. Releases are tagged with version numbers. GitHub's compare feature lets you review the differences between two versions to determine whether any parts of an SDK you use have changed. This helps you track modifications, assess risk, and decide whether an upgrade is necessary for your use case.

The URL for comparing two versions of an SDK is:

https://github.com/Files-com/<SDK>/compare/<OLD VERSION>...<NEW VERSION>

Replace <SDK> with the appropriate repository name for your SDK, one of: files-sdk-dotnet, files-sdk-go, files-sdk-java, files-sdk-javascript, files-sdk-php, files-sdk-python, or files-sdk-ruby.

Replace <OLD VERSION> with the tag matching your current version of the SDK, and <NEW VERSION> with the tag matching the release you want to move to.

For example, to compare the Python SDK from version 1.4.99 to 1.4.222, the final URL is:

https://github.com/Files-com/files-sdk-python/compare/v1.4.99...v1.4.222

Best Practices for SDK Upgrades

New versions of the official Files.com SDKs are published regularly, and bring better performance and access to new features. Recent versions also make support interactions easier and give you the full benefit of the SDK.

The practices below balance the benefits of staying current with the confidence that your critical bespoke code will continue working.

Manage Changes With Pinned SDK Versions

Pinning the versions of dependencies your code uses (including the Files.com SDKs) prevents updates from being applied automatically. This keeps unexpected changes out of production and gives you full control over when to introduce new versions.

The method for pinning varies by language. For most customers, we recommend pinning the minor version. For example, this allows an SDK to update automatically from version 1.2.3 to 1.2.4, but not from 1.2.3 to 1.3.0.

When an SDK is published with a new major or minor version, compare the differences to identify whether the new version requires any changes to your code.

Testing SDK Updates in a Staging Environment

If you rely on a custom solution built on a Files.com SDK for an important workflow, maintain a separate testing or staging environment. This lets you verify that your code (and the dependencies of your code) will continue to work when changes are made. Depending on what your custom code does, a staging environment might connect to your main Files.com site or to a separate child site.

A staging workflow helps you identify compatibility issues or breaking changes before rolling out updates to live systems.