Join us and get access to hundreds of tutorials and a community of expert Pythonistas.
This lesson is for members only. Join us and get access to hundreds of tutorials and a community of expert Pythonistas.
If you add new features or add a breaking change, you want to change the version of your package. In this lesson you’ll meet semantic versioning and how you can use it in your project.
Note: If you want to learn more about semantic versioning, make sure to check out semver.org.
00:00 Versioning is critical for letting users know the compatibility of a piece of software. You may be most familiar with certain versions of software having security vulnerabilities, or features missing in newer or older versions.
00:14 The most frustrating can occur when a new version of software breaks your project, so it’s definitely an important concept to understand when working with external pieces of code or giving your code to others.
00:24 PyPI requires a version when you upload a package, so that users know when the code changes. If you update your package and attempt to re-upload it, PyPI will require a new version number before it accepts it.
00:36 While there are many different methods for controlling version number, a common default is semantic versioning. This keeps your version in three components, each meaning something different.
00:46
Let’s head to setup.py and take a look. Here you can see your version is broken up into three segments. This first number is incremented when you make a major change.
00:58 Major changes can break code, where the API of your software is now different.
01:04 If you use a piece of software that’s 1.x.x and it’s updated to 2.x.x, there’s a good chance you’re going to have to do some work before you can make your software compatible with it. The second number is incremented when minor changes are made.
01:19 A minor change may be included functionality or new features, but it should remain backwards-compatible. Finally, the third number is incremented when patches are added.
01:30
Patches are generally bug fixes or closing up security vulnerabilities. Like minor changes, they should also be backwards-compatible. For this project, version is listed in two different places. You can see it in setup.py here, and you can also see it in __init__.py.
01:47
Now, I’m an expert at forgetting to update something when it’s located in multiple places, so fortunately there’s a tool available called Bumpversion. Open up your terminal and do pip install bumpversion.
02:05
Bumpversion is a great tool to keep your version numbers consistent. Let’s say we wanted to add a minor change to our codebase. You could just go ahead and type in bumpversion,
02:20
you should define what the --current-version is, which right now it’s 1.0.0,
02:30
and it’s located in setup.py, and in reader/__init__.py. Now when you run this—
02:41
oh, let’s see what’s going on here, No file or directory.
02:46
And it’s because I’m not in the correct directory, so let’s just change directory into the actual project folder and run the same command. Cool! No errors, and you can see your version here is "1.1.0".
03:01
And if you go to setup.py, it’s also "1.1.0". Now, if you look at the line that you had to type out to do that, it was quite a bit in there.
03:10 Bumpversion has a feature where you can set up a Bumpversion config file that will keep track of everything for you. If you’re interested, head to their documentation and take a look at how to set one up.
03:23
Once you have the config file, all you would have to do is call something like bumpversion major or bumpversion minor, and it would do all of your updates for you. For larger projects, this is a great tool to use. Okay, now that you’ve got a handle on versioning, the last thing you need to learn is how to include other types of files into your package before you can build them.
03:46 We’ll talk about that in the next video. See you there.
Become a Member to join the conversation.
