refactor centos to opensuse migration (#485)

[Hooverdan96]

Fixes #485

This pull request's proposal

• move to more generic CentOS to openSUSE description
• rename file, update toctree and add entry to redirect.txt file
• refactor text to remove v4 references, where applicable, and refer more to openSUSE versions.
• semantic line break updates
• replaced you/us/we with other terms/constructs.

Checklist

• With the proposed changes no Sphinx errors or warnings are generated.
• I have added my name to the AUTHORS file, if required (descending alphabetical order).

[Hooverdan96]

@phillxnet, @FroggyFlox please check out this version.

linkcheck failure due to timeout here (but work accessing directly).

(       data_loss: line  207) timeout   https://subspace.kernel.org/etiquette.html - HTTPSConnectionPool(host='subspace.kernel.org', port=443): Read timed out. (read timeout=20)

[phillxnet]

@Hooverdan96 Thanks for these improvement. As always much appreciated.

But I can't easily see the actual changes you have made. This may be an artifact/limitation of the GitHub interface or the procedure you used in this file rename. I.e. The GitHub web-UI shows the old file as deleted, and a new one authored by this PR. That is not what has happened here. Did you actually rename the file, or delete and copy the contents to a new file. The issue is that of history in the file, and ease of assessing changes.

Let me know if you wiped the file and created a new file, or renamed the existing file and applied the changes. It is always good to preserve contribution history and this can be lost/miss-attributed when we delete a file and create a new one. Sometimes Git can pick this up and show the changes. Otherwise, in this case it seems to be the case, we loose all attribution to the files history.

Ideally we need to see the changes made, not just a new file as-it-were. Then we can see the progress of that file. Less important in docs (but not ideal as it wipes attribution) but more important when dealing with code as all history of renamed and modified file (if resulting from a cut & paste & edit) is lost. So we have no history there.

Only one modification suggested: but could you also try to re-present this PR which the file rename recognized by git: that way the history of the files contents: including it's rename, can be assessed. More of a practice to ensure we don't loose history for when we do the same in code really.

Take a looks at the "Files changed" GitHub tab in this PR. It shows a deleted file, and a new one (the re-name suggested in the commit message) Git and I'm pretty sure GitHub Web-UI can reflect a rename if done in a git aware fashion. And we then get to maintain history and can see the actual changes made to a file.

If it helps, try starting from the master again and copying in new contents to the existing file. Commit that. Then rename the file, and commit that. Git can then see it as a filename change. Better still is to use the proper git mv thus no relying on git magic to know what file turned into what differently named file: where my suspicion here is that as the file contents were also changed it couldn't connect the old file contents to the new file contents. Hence the more robust approach of using git mv as you then announce the filename change to the version control. Without this care we will end up loosing info about history of a files contents. Again attribution concerns over time in docs, but functional regression ananysis concerns when we do the same in code.

Hope this makes sense. In short, to preserve file history (including name change) we have to explicitly use git mv to anounce this and avoid too much magic which will fail if a files contents are changed. Plus we hopefully get a better PR to be able to see exactly what has changed.

Thanks and my apologies for this run-around. But it's good to get familiar with such approaches else all renames of files loose all original authorship/contribution history and I think with git mv we can avoid this entirely. Plus we may well have a bunch of such changes coming up in rockstor-core so best we get more familiar with preserving git history over filename changes such as this.

[phillxnet]

@Hooverdan96 A reference re my suggestion to start over from master and using git itself to do the rename:

https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository

Moving Files

Unlike many other VCSs, Git doesn’t explicitly track file movement. If you rename a file in Git, no metadata is stored in Git that tells it you renamed the file. However, Git is pretty smart about figuring that out after the fact — we’ll deal with detecting file movement a bit later.

Thus it’s a bit confusing that Git has a mv command. If you want to rename a file in Git, you can run something like:

$ git mv file_from file_to

and it works fine. In fact, if you run something like this and look at the status, you’ll see that Git considers it a renamed file:

[phillxnet]

So with a new PR, resourcing git mv we should be able to see the changes you have made to this file (including filename change) and also preserve its history. My apologies is this is too laboursome, but I was also hoping to pass-on some git knowledge that should help us all in the refactoring to come in rockstor-core.

And of course, and as usual, my apologies if this is all just an artifact of the tools being used. But I've seen file-renames appear in the GitHub PR previewer before and it should also then help to see what you have changed in this PR.

But what-ever the only change I see that is needed is that sentence and don't worry about my attribution on that one. Hence the suggestion re starting from mater and applying your new content to that but ensuing the filename change is recognised by git, which doesn't look to be the case here. But should 'take' if you do it explicitly via the `git mv' command.

Let me know if you would rather me manage this, but it's a handy trick to be aware of, and we can both then see if this is the preferred method.

[Hooverdan96]

@phillxnet, strange. I believe, I renamed the file, and not delete it and then creating a new one. so, not sure. I will follow your suggestion (and thanks for passing on the github knowledge, there's always something to learn) and represent the PR.
I probably did the renaming part using the file manager function, and not the git command line. May be that's what caused it not to be recorded (though other manipulations seem to be recorded fine, like moving a file from one directory to another using the file manager). In any case, I'll try the git mv and see whether that will take care of it.

Hopefully, it will then show as a rename/move. Until then I will leave this PR open, just in case.
No worries about the run around, this was not a major change of things, and the content edits are already done (since that usually takes the most time).

[Hooverdan96]

ok, this is very strange. I'm using github Desktop for the commit, push, etc. (on an openSUSE VM).

However, I now went to the command line, used git mv to rename the file. This became immediately visible in the change history on Github Desktop. Then I proceeded to make changes to the file Still I could see that there was a file name change and then changes within the file.

So I proceeded to do the remaining changes in the other files.
Then I ran the commit (using the Github Desktop UI button) and push.
On GIthub and the change history (on Github Desktop) it now presents as before, one file deleted, a new one created, no visibility to the git mv that I executed.

Well, I guess it's Github Desktop's fault ... found this:
desktop/desktop#9146

so I assume, I have to do the whole thing manually on the command line, especially when there is a rename/change involved. Back to the drawing board!

[Hooverdan96]

It looks like, if I create multiple commits (I squashed them last time), then on the commit history one can see the changes. The summary view of files will still show as if one file was deleted and a new one was created. I'll present it like that, and you can take a look. I will reference this PR (unless you don't want me to). And if that works, then I can close this one.

[Hooverdan96]

Closing this PR now, as #508 seems to be the viable path forward