Software Engineering
versioning configuration semantic-versioning
Updated Tue, 13 Sep 2022 17:58:24 GMT

What Semantic Version increment to use for a filename change?

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?


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;

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:

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();

Comments (5)

  • +2 – "I highly advise against releasing 2.0.0 the day after 1.1.0." - why would that matter? The major version bump signals there is a breaking change, so users can take the time they want before updating. — Aug 11, 2022 at 15:41  
  • +1 – I'm not sure what it means to "support the... alias"? A program has one specific identifying name on the system used to invoke it. Is there some system-level thing that allows two different names to invoke a program (specified internally by said program)? — Aug 11, 2022 at 15:52  
  • +1 – @Erik Thanks, updated. This is exactly why I hesitated to provide any example at all until I realized some people couldn't grok the concept presented. — Aug 11, 2022 at 17:39  
  • +3 – @DanielR.Collins You can pretty always make a new command line program that does nothing but calls another one. Certainly you can argue that it's technically two different programs with two different names, but it has the effect of two names for the same program. No special system-level support required (though you may need some if you want to make the indirection closer to unobservable). — Aug 12, 2022 at 06:46  
  • +1 – @MonkeyZeus: Pople are probably confused because the question is about changing the name of a command line program, but your example seems to be about changing the name of a class, which is a completely different thing. Can you even write command line programs in PHP? — Aug 13, 2022 at 10:04  

External Links

External links referenced by this document: