borg vs borg2 - Name should change

[dagelf]

If an application makes breaking changes, its best to change the name. Reason being that a lot of dependent automations and wrappers will break. I propose borg2. Both old and new can be shipped in the same package. Borg2 can eventually replace borg, but just with a wrapper that makes the command line interface compatible so that old wrappers can continue working.

[ThomasWaldmann]

Yes, I agree that the borg 2.x cli name should be borg2 until some admin decides otherwise. So both borg versions can be run in parallel until the migration is completed.

Not sure if distributions should also switch their borg 1.x packages to a borg1 cli command name, but guess that would be best so one can have a symlink borg -> borg1 or borg -> borg2 and also directly invoke borg1 or borg2.

The remaining question is the mechanism implementing that cli command name and who implements that.

Here i think this should be a distribution-specific mechanism like the "alternatives" system of debian/ubuntu or a manually managed symlink. Thus, either the dist package maintainer or the sysadmin would implement this.

For the software and documentation in the borg github repo and the python pypi package, I would like to keep the "borg" cli command name and also the borgbackup pypi package name.

[ThomasWaldmann]

@dagelf BTW, iirc this was discussed before - maybe you can find the old ticket and link it from here?

[dagelf]

Also reference discussion about this started by @elho in the announcement thread: #6602 (comment)_ (I had to dig a bit, forgive me for opening a new ticket - but I think this warrants discussion separately)

This is a tricky thing. I can understand the desire to keep the name consistent or the same, especially from the documentation perspective.

I am approaching this from a systems administrator and end-user perspective. Changing the functionality of a command, without changing the name of the command, can cause immense frustration and misunderstanding - not to mention a flood of new tickets about unexpected behavior from uninformed users.

It seems borg2 will bring substantial changes, not only in the command line interface, but also in functionality, and dependencies.

I would strongly urge us to either adopt a new naming eg borg2 - indefinitely - and seeing as that command line options changing will require a lot of documentation updating, to start with a clone of current documentation and have separate new documentation for borg2. (Which can also be linked from what will become the legacy borg documentation and archives. Either that, or we have to try to keep the command line options the same, and implement backward compatibility indefinitely. Then none of this is needed.

The problem is, that, people learn commands, and are very slow to learn new commands - not to mention the ecosystem of dependent apps that has already evolved. Some users may never migrate - archives are usually made to be kept for years, if not decades. Trying to access your archives in 10 years' time, finding that the whole world has shifted underneath you, could be a most frustrating experience, which can be prevented with just a simple decision here and now.

I will dig for a roadmap now to see what has been discussed and planned already.

There is no shortage of commands in existing packaging that has had almost no updates in a decade. Borg could be like that, when the party can shift to borg2.

[ThomasWaldmann]

Our docs are versioned and automatically created from tags in the github repo (see the version selector at the lower right), so users are expected to read the docs version matching their borg version.

They don't always do that (or do not read the docs at all), but that is not our fault. :-)

[ThomasWaldmann]

To keep archives for longer, users are advised to create new borg 2 repos and then use borg transfer to copy all their existing archives into it. That avoids the issue that you would have to use an old (and by then unsupported) borg 1 version to access backups in some years in the future.

[dagelf]

The problem is that many people create archives and then forget about it. They might only get the message to migrate 10 years from now.

[ThomasWaldmann]

Guess they would notice by the time when dists start to remove the borg 1.x package (see the python 2 to 3 migration).

[dagelf]

The Python migration was one of the biggest disasters in modern software IMHO. Ironically, because of the pervasive workarounds such as virtualenv, and versioning the Debian packaging python as python2 and python3 isn't necessary anymore - but only because they both have the same cli interface. We should make technology easier to use and more inclusive! If 10000 people are proficient in Borg 1, and each has to spend 30 minutes to retrain to Borg 2, then we have wasted 5000 person-hours, ie. 2 person work-years of human endeavor... that could've been spent doing something new, instead of just the same thing differently. Doing this math about Python, and others, sets the mind spinning.

[deathtrip]

And what about the wasted man-hours spent on maintaining the backward compatibility you propose?
If someone finds their old archives are no longer supported, they can download an old borg 1.x version and still access those.

[ThomasWaldmann]

Maybe we could stick closer to the "name change" topic here.

[dagelf]

The major issue at hand is the new cli - as there are numerous frontends and automations that will break in all kinds of colourful ways. Hence my proposal to keep the new name borg2 in perpetuity.

And what about the wasted man-hours spent on maintaining the backward compatibility you propose? If someone finds their old archives are no longer supported, they can download an old borg 1.x version and still access those.

I think this is very much on topic. And the ability to do that using current packaging mechanisms without causing confusion, is what I want to help preserve.

My proposal is to side step this issue by not maintaining backward compatibility (assuming it is a burden) but instead just stick to a new name borg2. That way borg still works as it always has, even if abandoned. The only potential downside I see with this is that people will keep using the old version, but what we can do is update the defaults so as to make it future compatible.

Something that is not clear to me is whether the old binary can be packaged along with the new one, in the same package... that way no new packaging needs to be done anywhere. The only potential downside I see is that if a security issue does crop up in the old one, it might affect distribution of the new one, as they would be in the same package.

[dagelf]

To add, it leaves the option open to upgrade borg with a wrapper to borg2 - that maintains the old cli. Of course that will work best if borg2 can continue supporting the current algorithms. (I'm not yet familiar with the internals, so not sure how much of a burden it would be.) But it doesn't force it, it just leaves the door open.

To add... I volunteer. 😄 I don't see it as wasted man-hours if the balance is less wasted effort on the whole.

[ThomasWaldmann]

I don't think anyone would like to package borg 1.x into the same package as borg 2. That is just bad for maintenance and updates and just creates additional complexity and work compared to having 2 packages that live side-by-side and can be updated independently.

Guess this applies to (linux and other) dist packages as well as to the fat-binary packages provided by us.

BTW, the whole point of making a (breaking) major release is getting rid of legacy code, but there is another ticket that already described why that path was chosen.

[dagelf]

The other discussion, linked above, seems to center on two issues:

1. Breaking CLI changes
2. Dropping legacy crypto code

If the CLI stays the same, there should be no need for this ticket's whole discussion. So that brings up the question - how about that if borg detects :: in the CLI, then it uses the old format - otherwise the new. Ie. is it possible to make the cli trivially backwards compatible? Ie. no breaking changes in CLI - but do extend it with a new CLI format? My suggestion is just do this with a wrapper, if you want to get completely rid of old code in the main program.

As for introducing borg2 as a new package, it is easier to maintain one package than two... and we don't want people to keep installing the old version - hence the package name should stay borg. And it's justifiable if there's a roadmap to a merge. That way we can keep just one package borg - and as you initially suggested. If non-backwards-compatible CLI is a must, have borg2 as a command in it, and later drop the borg2 for borg, still in the same package - and If someone can't decompress a repo, they can just install an old version via pip, and that can be maintained and mentioned in the documentation. As for newer distributions and their packaging, you can expect them to not have old versions available anymore at some point.

People who only get introduced to borg now, won't have any confusion because new defaults can ensure that.

[ThomasWaldmann]

@dagelf You're late to the party: the old cli argparsing code is already gone and won't come back. the old crypto code is still there for migration reasons, but will be gone in 2.1.

Also, sorry for being repetitive: the point of the borg 2 breaking release is to get rid of a lot of legacy code, that includes the legacy cli argparsing. I won't write a cli-compatibility wrapper.

[ThomasWaldmann]

Also, I am closing this ticket now as it seems to be impossible to stay on-topic.