Drop short symlink to binary

[alerque]

I am a relative newcomer to this project, but just deployed it across a couple dozen devices on three continents. Remarkably I only ran into a handful of issues, and for most of those I see open issues for either fixing or documenting them. The most frustrating part of getting started was the confusing perceived lack of documentation. It turns out a lot of that was just a missmatch between the actual code and installations and the readme. The readme and some installations were referencing the client as inn, but others only had innernet. It took me quite a while to figure out that the short one was just a symlink to the full binary name and that I could safely ignore it.

As a long time sys admin and Linux packager (current Arch Linux TU, once PLD Linux core team member, etc.) I would like to suggest that this arrangement is trouble and should be dropped.

• It is difficult to package consistently. Especially for a Rust project without a real application build system (cargo handles the binary build fine but is not equivalent of autotools or cmake or meson or similar for full installs). Some systems (as I ran into) will not end up with the symlink at all. Even cargo install directly from crates.io is an example of an install that won't support that properly.

• It just makes a mess of documentation. Man pages are not accessible as man inn, and inn --help identifies as something other than the $0 as entered.

• Getting shell completion routines setup is just that much extra mess, and again not all distros are going to even end up with the symlink variant working right.

• Some systems won't support symlinks at all. Windows is going to require different shenanigans, Android is going to pose it's own problems with symlinks, etc. Just save people the trouble starting now and use the full innernet and only expect that one binarry.

There is nothing wrong with short alliases, but for Unix users these should be setup by the end user as alias inn=innernet. This will automatically take care of completions for most shells and has lots of other advantages, notably for documentation across platforms being consistent but people that type it a lot can still get a short command name.

[strohel]

@mcginty is the final authority here, but this makes good sense to me.

Very well explained @alerque, thanks!

[mcginty]

This makes sense to me, and thank you for such a well-justified PR. I agree this is the way forward, however I have some concerns about current users of innernet being confused by a command essentially disappearing from underneath them (assuming that not all users read the GitHub release notes :).

Unfortunately since I already let the cat out of the bag with this lazy symlink packaging method - I'm curious if there are any recommendations now for a smooth "transition plan" into using shell aliases vs. symlinks. I'm happy to make the diff larger if there's some temporary code to help migrate people. Ideas:

simplest version

Keep the symlink for one more minor version, but add a warning to the command output when argv[0] == inn that the symlink will soon be disappearing.

more complicated version

Provide the above warning, but also add a feature to "auto-install" the alias for a couple common shells.

Not sure if it's possible to add default aliases for shells in typical OS packages similar to completions or not, I haven't looked into it enough yet, but it seems like at the least it might be considered a hack.

[alerque]

As a Linux packager I can say that bundling aliases out of the box is pretty much a non-starter. Some systems have hacky ways of making this happen, some distros specifically outlaw it.

I would suggest a perhaps more aggressive variant of your first suggestion.

1. Document this prominently enough that anybody looking for it will find it (top of readme, pinned issue, etc.) Also document how to setup an alias.

2. Drop the symlink, and provide a stub inn instead that just throws an error message noting the change, showing how to make an alias, then exist with an error code.

3. Leave that in place for one release cycle, then drop it. Distro packagers would even have the option of not packaging that.

If you are less aggressive and just warn people with scripted usage will just ignore it anyway so you are really just putting off their pain for another release with no real gain. If you did want to be softer you could do it your way first, then in the next cycle you could do it my suggested way.

Also remember none of this will actually make it to everybody because in many cases distro packages already do their own thing. Dropping the symlink is something you can do for some distros, but some distros (e.g. Arch Linux) will need to drop the symlink in their downstream packaging. Others don't even have it yet so it is all moot.

[mcginty]

@alerque I like the stub binary idea that returns an error code! Since I was planning on doing a release imminently, maybe I'll the "soft" version where in this release I'll cherry-pick 4862984 right now, add code to print a soft warning, and then in the following minor release will do your stub idea.

Thanks again for your input from the perspective of a package maintainer, it's really helpful to understand that side of things.

[strohel]

Feels like a good time to merge this? The transition period has been long already. CC @mcginty.

@alerque would you mind rebasing on current main? The PR still applies, but the diff is a bit confusing as 4862984 was already cherry-picked.

[mcginty]

Agreed. It's been long enough, lol. Sorry @alerque for not having a more deliberate transition plan in place. Perhaps this is a good time to do a minor version bump as well?

[strohel]

Perhaps this is a good time to do a minor version bump as well?

Oh yeah!