Skip to main content

Parsons switching to Semantic Versioning

The Parsons library will be switching to a new method of labeling release numbers known as Semantic Versioning.

Published onJan 24, 2023
Parsons switching to Semantic Versioning

What is Versioning?

As software is developed, new versions get released over time. Versioning is the practice of giving each of these versions its own numerical label. Think about upgrading from Windows 7 to Windows 8, then to Windows 10, etc. Parsons is no exception to this, and the Parsons team periodically releases new versions of the library. Like Windows, Parsons has not always had a very regular way of labeling its releases with numbers. For example, we went from 0.18.0 to 0.18.1, and then to 0.19.0. But we went straight from 0.19.0 to 0.20.0. The current version of Parsons is 0.21.0.

Versioning is useful for many reasons. For a product like Windows, it provides a chance to sell your product again to users, and it gives users an incentive to pay for your upgrade. More relevant to Parsons, the version number can give useful information to users about if they should upgrade and how much change they should expect between versions. For example, I might have decided that sticking with Windows 7 was fine when Windows 8 came out. But by the time that Windows 10 was released, perhaps I decided that it was time to upgrade since I was getting behind.

Challenges in Versioning

When done inconsistently, versioning can create more confusion among a software’s users than it clarifies. Again, looking at Windows, going from Windows “Vista” to 7 to 8 to 10 created a lot of confusion about what you were actually doing when you upgraded your computer and if you had missed a version between.

A problem that users of a software library face, regardless of how the library is versioned, are breaking changes. Generally, when we add code to Parsons, we do so in a way that it won’t break existing code that uses Parsons. Sometimes this is not possible. In those cases we document the changes users must make to their code in the release notes that accompany the release. This can be hard to find, however, and can create surprise bugs for users when they upgrade their Parsons version. It also makes it harder for the Parsons team to add new features to Parsons, since we don’t have a standard process for balancing incoming breaking changes. We’ll see in a moment how better versioning practices can help solve breaking changes.

Semantic Versioning

Semantic versioning is a structured approach to versioning that has become common in the software industry. Each release has a major number and a minor number. The major number is the number before the decimal, and the minor number is the number after. So, version 3.11 is major version number 3, and minor version number 11. When you release a minor version you increase the minor version number by one. When you release a major version, you increase the major version by one and start the minor version over at 0. For example, you would perform minor upgrades from 3.11 to 3.12, to 3.13. Then you would perform a major upgrade to 4.0, then more minor upgrades from to 4.1, then 4.2, etc. This is a simplified type of semantic versioning that the Parsons library will be adopting. Semantic versioning as normally used is a little more complicated, but the ideas are the same.

How do you know if you are releasing a minor or a major version? If the new code contains breaking changes that will require users to change how they use Parsons, then it is a major release. If the new code does not contain breaking changes, and Parsons users shouldn’t need to take any actions after performing the upgrade, then it is a minor release.

What does this mean for users?

If you are an engineer who uses Parsons in your code, this will help you know what to expect when you upgrade your version of Parsons. If the update you’re making is only a minor version change, then it should be safe to do without any work on your part. For example, if you’re updating from 4.5 -> 4.11, your code should work when the upgrade is finished.

If the major version number is changing, then you will want to check the release notes for each major version upgrade to see if you need to make any adjustments to your code. For example, if you’re updating from 4.5 to 6.2, then you will want to check the release notes for the 5.0 and 6.0 versions, since they will both contain breaking changes. Those changes might not be to parts of Parsons that you use, so there is still a good chance you won’t need to make any changes to your code.

What does this mean for Parsons contributors?

Note: If you’re not knowledgeable about Git’s branch and pull requests concepts, you can check out this tutorial.

Going forward, the Parsons GitHub repository will maintain two branches which represent upcoming releases: the main branch and the major-version branch. The main branch will become the next minor-version release, and the major-version branch will become the next major version release.

When you submit a pull request for your code to be integrated into the next release, first identify if it has any changes that could break someone’s code. For example, changing the name of a function or requiring that an argument of a function is a different type could break someone’s code. (However, adding a new function to an existing class, or adding a new class, would not break any existing code.) If your code does contain a breaking change, you should commit your pull request into the major-version branch. If your code does not contain a breaking change, then you should commit your pull request into the main branch.

Periodically, the Parsons team will release a new minor version. When we do this, we will release the current main branch as the new minor version. This release will then be pushed to the PyPi host so that it goes out to users. When we need to release a new major version, we will merge the existing major-version branch into the main branch. Then we will release the main branch as the next major version.

Most pull requests do not contain breaking changes, so most PRs will continue to be committed to main as usual. If you need further help with this process, be assured that the Parsons team will help you guide your pull request into the right place throughout the process.


The Parsons team is excited to switch to a semantic versioning scheme. For anyone using the library at a basic level, nothing significant will change. For power-users of the Parsons library, this will make it much easier for you to anticipate the risk attached with each update of Parsons. For the Parsons contributors, this will make it easier for us to organize our work and reduce the chances code is broken by accident.

No comments here
Why not start the discussion?