More clearly define the current version and target version in upgrade documentation

[lethargosapatheia]

Change Type

Correction

Area

Installation/upgrade

Proposed Changes

I've done several (successful) upgrades for netbox, but whenever I do them, I always get a little bit confused about what directories I'm supposed to copy and where I'm supposed to copy them and then I realise that the instructions here are rather confusing and that this is isn't just my fault 🙂
https://demo.netbox.dev/static/docs/installation/upgrading/
The reason for that is that X.Y.Z refers both to the newly downloaded version and the current version you're using in two different consecutive code snippets. This refers to the newly downloaded version:

sudo ln -sfn /opt/netbox-X.Y.Z/ /opt/netbox

And this to the current version:

sudo cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/

I mean, sure, it is logical, because you've just created that symlink in /opt/netbox, but it's still rather confusing and you have to look and check several times until you figure out 🙂

It might be one of those small changes that can increase the readability of the documentation, but let me know if I'm reading this wrong :)

[jsenecal]

Hi @lethargosapatheia, would you mind wording the changes based on the current documentation ? How would you do it? Would you be able to submit a PR with those changes ?

[lethargosapatheia]

Unfortunately I've no idea how to submit a PR, maybe you can point me to it, but what I'd suggest, I guess, would be to replace this:

sudo cp /opt/netbox-X.Y.Z/local_requirements.txt /opt/netbox/
sudo cp /opt/netbox-X.Y.Z/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/
sudo cp /opt/netbox-X.Y.Z/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/

with this:

sudo cp /opt/netbox-current-installation/local_requirements.txt /opt/netbox/
sudo cp /opt/netbox-current-installation/netbox/netbox/configuration.py /opt/netbox/netbox/netbox/
sudo cp /opt/netbox-current-installation/netbox/netbox/ldap_config.py /opt/netbox/netbox/netbox/

The same thing with the following three code snippets:

sudo cp -pr /opt/netbox-current-installation/netbox/media/ /opt/netbox/netbox/

sudo cp -r /opt/netbox-current-installation/netbox/scripts /opt/netbox/netbox/
sudo cp -r /opt/netbox-current-installation/netbox/reports /opt/netbox/netbox/

sudo cp /opt/netbox-current-installation/gunicorn.py /opt/netbox/

Or let me know how I can submit the PR. I've identified the file at least: https://github.com/netbox-community/netbox/blob/3307bd200c38d2c548022917292c5f8db37c5541/docs/installation/upgrading.md

It can basically be anything that marks the difference between the new and the current version.

[jsenecal]

I would argue that introducing vA.B.C, and explaining the difference between vA.B.C and vX.Y.Z would be better.
Either that or netbox-[CURRENT-VERSION] and netbox-[TARGET-VERSION]. What do you think ?

[lethargosapatheia]

I think either of your suggestions is better than what I said because they're symmetrical. If you were to ask me personally, I'd go for [CURRENT-VERSION]/[TARGET-VERSION], but that's just because I bumped into this and wanted to know clearly which is supposed to be the current version. But I'm not sure how objective this is :) Either is good!

[gdprdatasubect]

Having stumbled across this before, X.Y.Y and X.Y.Z seems kinda fitting to me, because most people just upgrade whenever a new one is available

[lethargosapatheia]

It's hard to say, I'd instinctively say they look too similar (and in reality they actually are :) ), but as long as they are different, it will be a step forward.