Forem: Benny De Bock

Software Versioning: A brief introduction

Benny De Bock — Fri, 19 Jan 2024 10:01:59 +0000

Hello there!

As part of my current job, I've had to adopt a versioning system. "Why?" you may inquire. A fantastic question! And to answer it, I'll provide a brief introduction to versioning and its benefits.

We've probably all come in contact with versioning at some point; Be it libraries and frameworks you've used, products you've bought or even the games you've played. Every time something gets updated, a new version is created.

What is versioning?

If we take a look at Techopedia, Software Versioning is the process of numbering various releases of a software for internal usage and release marking. Simply put, it is a method of tracking and managing software changes. Each version reflects a unique state of the program at a certain moment in its release cycle.

How can we recognise when versioning is used?

When software is coupled with versioning practices, they are usually combined with a version number. This number usually consists of numerical and/or alphanumeric components that convey information about the program's evolution as well as its compatibility with previous or future releases of the software.

Some of the most common versioning schemes include:

Sematic Versioning (SemVer): The most popular method of versioning you'll find online. SemVer uses the major.minor.patch syntax, with major referring to software-breaking changes, minor referring to backward-compatible additions, and patch referring to backward-compatible bug fixes.
Date-based Versioning: Another typical method of versioning where the version number is based on the release date. Typically seen in the format of YYYY.MM.DD or YYYY-MM-DD. It provides a clear chronological order of releases, but it does not specify the extent or nature of the modifications.
Build Number: Where previously mentioned schemes used a sequence of numbers, some software employ a build number. This is a unique identification assigned to each build of the software. Build numbers can be sequential or include information such as timestamps or revision numbers, although this is not a requirement.

Why should I use versioning?

Now that we've covered some of the most prevalent versioning techniques, why would we employ them? There are several reasons why you should utilize versioning.

Tracking changes: Depending on the scheme you use, you may easily observe what has changed between software releases. This aids in the identification of new features, bug fixes, security upgrades, and other developments.
Compatability management: Perhaps most importantly, versioning allows developers and users to determine if a certain version is compatible with what they are working on. Consider a project that requires you to routinely update your dependencies. If the dependence has a good versioning scheme, you can estimate how much labor it will take to update it.
Documentation and communication: Versioning is similar to preserving a record describing the history of the software. It explains how the codebase evolved and the decisions that led to the change. Usually, changes to the versioning number are accompanied by a full explanation of what happened and why. This communicates efficiently with all of its users.
Release management: Versioning is essential for controlling and coordinating software releases. It assists in the planning and prioritization of feature releases, bug fix updates, and patch releases. It also assists users with identifying and installing the correct version of the software.

Closing words

For the aforementioned project, we chose to use the SemVer versioning method, which has resulted in improved documentation and change detection.

Introducing versioning may be extremely beneficial not just for increasing team communication and documenting your code, but also for clients/users that utilize your products. It enables teams to retain a disciplined approach to change management while avoiding compatibility difficulties.

For additional reading on the topic, I recommend checking out these articles!

How to contribute to open source as a junior developer - My experience

Benny De Bock — Sat, 02 Jul 2022 18:40:20 +0000

Hello there!

Have you ever been in a position where you want to contribute to open source projects, but you don't know where to start? I sure have, but through my internship at Broken Hands, I was able to gain experience in open source, more specifically in the Vapor ecosystem. As such I want to share these experiences and tips with you.

Finding an open source project

Finding a project you want to contribute to can be daunting, as hundreds or thousands of developers can be actively contributing to these projects and there are so many of them. My advice for you is to look either for an open source project that you are using in any of your projects. Or alternatively, if you want to gain experience in a certain programming language, search for projects in that language.

On GitHub you can do this by searching any keyword that might interest you (a good one is open source) and filter the results on the programming language you would like to work in. If you don't find the language of your choice in the list, go to the advanced search feature. In there, you can specify the exact language you're looking for.

Another way to find project to contribute to is by exploring this GitHub topic page with good first issues. The filtering of these issues is not as expansive as the advanced search, but for popular languages, this shouldn't be a problem.

There are also some great sites that can help you in your search such as:

I've found a project, what now?

Now that you have found a project you would like to work on, it might be hard to know where to begin.

README

A good start would be to read the README of the project. This can contain useful information about the project, as well as how you can contribute or the guidelines to contributing. They can also include other contributors and where you can find the community to ask questions or to chat (e.g. Discord, Slack, etc.).

Project Boards

Although the chances of these are lower, some projects might have a project board available with beginner issues. These are a great way to get an introduction into the project and to start off your open source career. These can gain you some confidence.

If there are no project boards with beginner issues, you can also go to the issues tab and search by these criteria: is:open label:"good first issue". This will show you issues that aren't resolved yet, and they're a great starting point to get familiarized with the project.

Note: In the best case scenario, the issue you pick should have instructions on how to recreate the bug, or the specific circumstances it happened under. If this is not the case, you can ask the creator of the issue if they are able to share how to recreate it.

Create a fork

In most projects, you won't be allowed to create a branch on the main project. Thus, you must create a fork of the project. You can do this by clicking on the fork button in the top right corner of the repository.

By doing this, you will copy the repository to your own personal GitHub or any other organization that you are the owner of.

Once you have forked the repository, you can start working on a fix for the issue you have chosen.

Testing is important

You can fix an issue, but how did you manage to replicate the issue? To avoid someone else having to replicate the issue, but also to make sure that the behavior that was faulty doesn't come back, you should write tests. Writing these tests will make your code more robust, as you can check for scenarios that pass and scenarios that fail. But you also create a guarantee towards the future that the unexpected issue from earlier cannot come back when it's being iterated upon, as it is an extra check now.

I have fixed the issue, now what?

You have fixed the issue, great! But this fix is not yet available in the original repository. We do this by creating a pull request. Normally, when creating a pull request, this is done from a branch of the repo, to the main/master branch. However, since we created our own clone of the repository, this is not possible.

Though it can be hard to see, you have the option to compare across forks of the repository.

By choosing this option, you have have to pick the repository that you forked, along with the branch you have worked on to be able to see the differences in code. If there aren't any merge conflicts, then feel free to hit that Create pull request button.

Writing a proper pull request

To create a proper pull request, it is important to shortly describe in the title of the pull request what it tries to solve/add. You can go into more detail in the comment section of the pull request as to which files you have changed, the behavior you have adjusted, as well as which issue it relates to. The latter can be done by typing something similar to Resolves #<number> where the <number> is the ID of the issue you are referencing.

An example:

Note: It is also possible to create a draft pull request. This means that you can show others that you are working on the problem already, but you are not able to release it yet as working code. You can use this to get feedback beforehand from the main developers or the community.

Getting a pull request accepted

Once you have created a pull request successfully, some automated tests might be running. If they all pass, and there are no merge conflicts then you should see something like this:

This does not yet mean that your contribution has been accepted. In a lot of cases, the incoming pull requests need to be approved by the core team. They may request changes and you can go into discussions about why that is (or isn't) a good idea. Once you have gained the approvals, then your work is done.

Congratulations!

You have successfully contributed your (possibly) first pull request to an open source project. This may be the first of many more to come. Just remember that you can do more than you think, if you set your mind to it.

For me personally, the main takeaway I had from working in open source was that I shouldn't be afraid to interact with the community, ask questions and even make mistakes. We all start somewhere. Contributing to open source is a great way to get experience, getting better as a developer, as well as making connections with other developers.

If you think I missed something, feel free to let me know in the comments. This is my first time writing a post so feedback is always appreciated.