What Semantic Version increment to use for a filename change?

Question

I have a program that runs on command-line, let's call it myprogram 1.0.1. It's published on GitHub.

Now I discovered that name already exist for a well-know software, so I want to change the name from myprogram to myprog. This, of course, will break the old usage of command since the user now must type myprog and not myprogram anymore.

The code remains the same.

Any suggestion?

Answer 1

I think myprogram needs to release 1.1.0 which supports the myprog alias. If the user invokes myprogram then it should present a notice/warning to the programmer that this name will be deprecated in the next major version release.

Upon release of myprog 2.0.0, myprogram should no longer work. The release of 2.0.0 could be nothing more than a name change. This will help to make the transition easier for developers since they have to worry about just a single compatibility-breaking change.

An alternative route is to fork myprogram into myprog and issue an abandonment notice like PHPExcel did; https://github.com/PHPOffice/PHPExcel

Whether or not your software rename constitutes a bump down to 1.0.0 instead of 2.0.0 is not a choice I am familiar with.

---

Regardless, I don't think versioning is going to be the big stumbling block but rather the name change itself. It sounds like a headache especially if people come across old tutorials for myprogram and are not aware of the name change.

---

Aliasing example in PHP:

<?php
class myprogram
{
    function __construct()
    {
        trigger_error( 'myprogram is being renamed to myprog in v2.0.0. Please consider switching to myprog today.', E_USER_NOTICE );
    }
}

class myprog extends myprogram
{
    function __construct()
    {
        // empty to avoid calling myprogram's constructor
    }
}

$myprogram = new myprogram();

Answer 2

Since this is a backward incompatible API change, you should bump to 2.0.0. Changing the name of a command line program is backward incompatible because the name is part of the API, and scripts and other tools using the program will stop working.

It might seem a big version jump for such a tiny change. But in semantic versioning, the version numbers does not reflect how big the changes are. They only reflect how the changes impact other systems which use your program - do they need to be updated or not?

Answer 3

The semantic versioning defines versioning rules solely in relation with the API, as it aims to facilitate the management of dependencies between packages.

Regarding the command line you are in a grey area. It is a user interface but at the same time it could be considered as a programming interface (e.g. in scripts). So it's up to you to define how you see it:

• You may consider that the programme name is part of the API. Since any shell script would break with your new version, i.e. no backwards compatibility, you would have a major version increment.

• You may consider that the programme name is not part of the API and that it's only a particular binding. The real API (parameters and options) is unaltered. In this case, you should consider a minor increment.

A major version for no new functionality does not feel right. Offer as part of the installation script or in your API documentation an optional creation of an alias or a copy with the old name to ensure backward compatibility. You can then go for the minor version with good conscience.

Answer 4

The purpose of semantic versioning is effectively to communicate a certain kind of change to the users of an API. But when you change the name of a command line tool, this alone seems to be a very clear communication to any command line programmer that the API has changed.

So you can change the major or minor version number, if you like, or keep it, or set it down to 1.0 for the new name, it will actually don't matter. If your intent is to show to the users that no functionality has changed, you should probably keep the old version number. But because of the name change, they cannot rely on that alone and will have to read your changelog either.

Answer 5

The semantics of your code haven't changed - if I call your code, it will act exactly as before. What changes is how I call it (which name to use). But that's something the user most likely could have done themselves. I can rename an executable file that I downloaded, and that doesn't change it's semantic version.

Exception is if the name of the executable is relevant to it its operation. For example, at runtime your code would read the name of the executable "myprogram" and would create a directory "caches/myprogramcache". And that stops working when the executable is renamed to "myprog" because now it looks for a directory "caches/myprogcache". Probably best to avoid this.