Understanding RPA Framework Package Versioning

At the core of Robocorp’s robotic process automation capabilities is the RPA Framework keyword library; an internally-managed and owned package that leverages and extends both Robot Framework’s built-in and external libraries to better fit the needs of Software Robot Developers.

Since this package is so integral to RPA development on the Robocorp platform, new versions of the package with additional features and fixes are released very frequently. As these features may introduce breaking changes, and may not be compatible with earlier versions, the RPA Framework package is purposefully not auto-updated for Robocorp Lab users.

Therefore, it is at the user’s discretion as to whether to update this integral package or not. Obviously, our users may wish to do so to get the latest features and security fixes available but there are some important considerations that we want to make clear. First, let’s consider...

What Major Version of RPA Framework Is My Robot Using?

You can determine which major version of RPA Framework one of your robots is using by opening the project in Robocorp Lab, or your favourite text editor, and then opening the conda.yaml file.

  - defaults
  - conda-forge
  - python=3.7.5
  - pip=20.1
  - pip:
      - rpaframework==6.*

You can see in my conda environment that the robot is using rpaframework major version 6, but following the major version number is a wildcard character (*). The presence of the wildcard character is related to Robocorp’s adherence to Semantic Versioning principles and using it has consequences that need to be well-explained.

When using Semantic Versioning, a version number has three components: MAJOR.MINOR.PATCH Changes in each of these numbers signal different levels of possible internal updates to the package:

  • MAJOR updates can change or remove core existing features or functionality and therefore can cause compatibility issues with earlier major versions of the package.
  • MINOR updates can add new features, but should not break any of the package’s existing functionality.
  • PATCH updates can fix existing features or bugs, but should neither add to nor break any of the package’s existing functionality.

For my robot then we can see that whilst the major version of the rpaframework package is specified with a 6, there is a wildcard character where the minor and patch version numbers should be. By not specifying those two version numbers, my robot will use whatever is the latest minor and patch version for the rpaframework package major version 6 that is installed on my system. This is great as I get the latest non-breaking features and fixes for rpaframework as they are released but there are some quirks that come along with it. We’ll explore those now.

Why Is the Wildcard Character (*) in My RPA Framework Package Version Notable?

When a user first installs Robocorp Lab, or the VS Code extensions, the bundle of dependencies that are required to run it are cached on the user’s disk drive to ensure faster builds on subsequent updates. The way that we cache the dependencies means that it is not immediately clear which minor or patch version of rpaframework your robot is using, since the wildcard character in the package version 6.* will use whatever the latest version of it available in your cache is.

In other words, two users both with rpaframework==6.* in their conda.yaml file might actually be using different minor or patch versions of the package depending on what version has been cached on their disk - it’s not made clear which version is actually in use just by looking at the package number in the conda.yaml file.

However, you can determine which exact version of rpaframework is in use with the following steps:

Determining the Exact Version of RPA Framework In Use

In Robocorp Lab:

  1. With the project open in Robocorp Lab, click File > New > Terminal from the menubar
  2. In the Integrated Terminal window type either:
    • pip show rpaframework
    • conda list -f rpaframework

Robocorp Lab rpaframework package version in integrated terminal

In VS Code:

NOTE: this requires the Robocorp Code and Robot Framework Language Server extensions to be installed in VS Code.

  1. With the project open in VS Code, open an Integrated Terminal by clicking Terminal > New Terminal from the menubar
  2. Open the VS Code Command Palette using Ctrl (Windows,Linux)/Cmd (OSX) + Shift + P
  3. Search for, and then select, Robocorp: Run Robot then, Run robot: <your-robot’s-name>
  4. Look for rpaframework in the Installed pip packages: output that is printed to the Debug Console

VS Code rpaframework package version in debug console

Please note though that as long as the wildcard character (*) is included in the rpaframework package version number set in conda.yaml then you cannot guarantee which version of rpaframework will be used.

Okay, So Is This Variable Package Version Number a Problem for Me?

Whether this is a problem for you depends. If you are just exploring and building robots then you don’t need to change anything: keep on building! If your robot works with a major version, then it will continue to work with that major version regardless of which minor/patch version of rpaframework you are using.

However, here, for example, are some cases where the variability of the rpaframework package might be a problem for you:

  • You want to ensure your robot doesn’t break with new features and fixes released into the package
  • A new feature update will introduce a backwards incompatibility into your working robot
  • You want to test a specific feature that’s only available in a certain version of the package
  • You want the latest bug fixes but not any major feature changes

Yup, This Seems Like a Problem for Me… How Do I Fix It?

The best way to ensure that unexpected changes and bugs aren’t introduced to your robot project, is to specify an exact version of the rpaframework package to use. We recommend that users with a need for a specific version of the rpaframework package adhere to software development industry best practices and ‘lock’ the version of the package they are developing robots with. (You can read a fuller explanation of ‘package locking’ here)

To ‘lock’ the RPA Framework package version you are using, we need to open the conda.yaml file again and set the rpaframework package to an explicit version number: how strict your ‘locking’ will be depends on your own specific use case.

Feature-based Soft Version Lock

If my robot needs a certain feature I want right now I can define an exact major and minor version number to get it. I can, however, keep the wildcard character in the place of the patch number to ensure I get the most recent non-breaking bug and feature fixes.

  - defaults
  - conda-forge
  - python=3.7.5
  - pip=20.1
  - pip:
      - rpaframework==6.3.*

Strict Version Lock

By setting the rpaframework package to an exact version number we ensure that the robot is executed with that exact version. We won’t get access to any new features or fixes, but we do benefit from knowing exactly what functionality our robot is running with.

  - defaults
  - conda-forge
  - python=3.7.5
  - pip=20.1
  - pip:
      - rpaframework==6.3.1

How Do I Update the Package After 'Locking' It?

By setting the version number to an exact number, I now have the responsibility to manually update the rpaframework whenever I see an update that will be useful to me (you can get notifications of rpaframework updates in Robocorp Slack - join up if you haven't already!)

Whenever I see an update available to rpaframework that I might want to use, I will first go to check the RPA Framework Release Notes. There I can read the release notes and determine whether I will introduce any breaking changes to my robot project by using the newer version before I manually update the rpaframework package version number in my conda.yaml file again. Your own specific needs for your robot will ultimately affect when and how often you as the Software Robot Developer want, or need to, modify the package version and perform local testing and fixes.

And that’s all, happy bot building! 🤖