Back-end Engineering Articles

I write and talk about backend stuff like Ruby, Ruby On Rails, Databases, Testing, Architecture / Infrastructure / System Design, Cloud, DevOps, Backgroud Jobs, and more...

Twitter:
@daniel_moralesp

2019-01-11

Versions & Releases in Open Source Projects - Part 1

One of the first things you need to understand in the software development world is that open source programming languages and the software we create are permanently attached to a given version. Versions mean the expected evolution of the tool, language, or software. The tools we make are not static; they always need to improve their behavior and results. 

Youtube video about this post: Part 1: https://www.youtube.com/watch?v=kTKVQy9Je1I

1.1 Versions & Releases in Open Source Projects - Part 1

For this reason, we see some kind of cryptic versions like 1.0.3, 5.2.4, or even something more challenging to understand, like 2.5.6-rc. These are also called releases. So, for instance, if we go to this page: https://www.ruby-lang.org/en/downloads/releases, we can see the different Ruby versions/releases over the years. So, for example, you can see something like Ruby 3.0.0-preview2 or Ruby 2.6.0-rc2. But, on the other hand, if we go to this other web page: https://weblog.rubyonrails.org/releases/, we will encounter an overwhelming amount of content related to all of the Rails versions over the years. 

If we are just starting or have some expertise in the field, this is a significant amount of content to consume, understand, or even test. To feel less overwhelmed by this, we need to understand some basic concepts related to versioning or releases.

Version when you install the library


When you install a programming language, tool, software, or library in your operating system for the first time, the version you installed is almost always the stable and latest version (obviously, if you don't type any particular version to install). When we talk about the "stable version," we are talking about something we can use for sure. It is a version that is already tested in production, and we can be confident that we won't encounter any bugs related to versioning, security, or other weird things. Therefore, it is the default and recommended installation. However, in some scenarios, you need to be careful about the version you are installing because you can find some gotchas like this:

  • * You're following a fantastic tutorial, but it was created 5 years ago. That means that the instructor probably installed the last version at the time. But you're now in the future, so you need to be careful about this, or you'll have problems following that fantastic tutorial. What you can do here is to give the order to the system to install the very same version of the instructor and avoid potential problems later

  • * You're the new senior developer at Shopify (I hope you achieve this). You'll need to install the identical versions that the platform is running right now. You're in your first week of the job, and you're just familiarizing yourself with the code, not upgrading the whole project. You need to take care of the current versions of the project and avoid problems

  • * You're creating your own project, and you want to install the very last version of Rails, so you want to use Rails 7 and Ruby 3 (at the current time). Not a problem because you're creating everything from scratch. Probably you don't need to be careful about versions

As you can see, versions matter, so you have to take all of this even before starting programming.

Changelog


Now that we understand better versioning, it's time to see the next fancy term: Changelog. We need to refer to something ubiquitous in software development to understand this word: Logging. In computing, a log file is a file that records either events, other runs, or messages. Logging is the act of keeping a log. But we're talking about Change-log. 

When we are talking about versioning, we will encounter this proper file named Changelog, where at a high level, we can see the changes made inside the software for this particular version. So, if we see the Changelog of the Action Cable module in Ruby on Rails up to version 5.1.4, https://github.com/rails/rails/blob/v5.1.5.rc1/actioncable/CHANGELOG.md, you can read the changes over the versions in that module.


Changelog


It's important to note that not all languages, tools, or software have this Changelog file or be named differently. For instance, in Ruby, you can see something like this: https://www.ruby-lang.org/en/news/2021/07/07/ruby-3-0-2-released/.

In this case, if you hit that link, you'll be redirected to GitHub with all the commits of this particular release. Sometimes is more challenging to read and understand the changes this way, but it is what we have, and if we need to study the changes made by creators, we need to go through the commits.

Semversion


The following term we need to understand is Semversion. We want to decrypt the fancy numbers like 5.2.1 or 6.0.1. Let's go ahead. Semversion is equal to Semantic Versioning, and you can read the numbers like so: MAJOR.MINOR.PATCH. Source: https://semver.org/ 

Almost all new languages, tools, and software follow these semantics.

  • * MAJOR version. When you make incompatible changes. Basically, these changes can break your code. But when could this happen? Basically, when you're upgrading your versions. For instance, if you have the Rails 4.2.11 version running in your current project and decide to upgrade to Rails 5.2.6, you'll probably have incompatible code and need to refactor or completely change some parts of the code. This can generate a lot of confusion or become your code a mess; for this reason, you'll need some experience to make the right changes

  • * MINOR version. It is when you add functionality in a backward-compatible manner. In this case, you want to upgrade from Rails 5.0.7 to 5.1.7. We won't encounter more significant issues, and we can upgrade versions smoothly

  • * PATCH version. It is when you make backward-compatible bug fixes. In this case, we won't have any issues, so we can upgrade easily


Release Candidate


Youtube video about this section here: Part 2: https://www.youtube.com/watch?v=3GH_trh5Ri8

1.1.2- Versions & Releases in Open Source Projects Part 1


Release candidate references agile software development and is the situation when the new version is almost ready, is already tested, and has a low number of bugs. This doesn't mean that the version doesn't have any issues. Instead, it means that we need to act carefully with these versions because it is a candidate but is probably not wholly usable yet. 

The primary purpose of this type of version is to spread among early adopters, who are willing to use it in a dual-booting mode or in different environments like staging and provide feedback to the creators or even to finally use it in the project they're working on.
If we see the image above, we have two main divisions: 
  • * Testing and development period
  • * Release period

Source: https://en.wikipedia.org/wiki/Software_release_life_cycle

"A release candidate (RC), also known as "going silver," is a beta version with the potential to be a stable product, which is ready to release unless significant bugs emerge. In this stage of product stabilization, all product features have been designed, coded, and tested through one or more beta cycles with no known showstopper-class bugs".

The way we can differentiate a release candidate in the semversion jargon is with the word: -rc





Release Notes

The release notes are very similar to Changelog. However, we can see the overall changes, not just a module change. These are the kind of notes we need to check when we want to upgrade our current version to a newer one and see if something can break our code. Here we can see the release notes of Rail 6.0 https://guides.rubyonrails.org/6_0_release_notes.html.


The same notes say: "These release notes cover only the major changes. To learn about various bug fixes and changes, please refer to the changelogs or check out the list of commits in the main Rails repository on GitHub."

I hope you've learned about this topic; see you in the next blog post.

Thanks for reading!
Daniel Morales





@daniel_moralesp