Outdated Guide in Cortx Readme

[stx-hseow]

As I came back to try out the new release, I realized that the Guide is still pointing to old OVA (1.0.4) guide. So I created a pull request.

Wouldn't it be better to not specify the version for the latest release but instead archive the old ones?

For example:
Latest guide: [CORTX virtual machine image](doc/ova/latest/CORTX_on_Open_Virtual_Appliance.rst)
Archived guide: [CORTX virtual machine image](doc/ova/2.0.0/CORTX_on_Open_Virtual_Appliance.rst) (depending on the version)

[hessio]

Hi @hseow-seagate I am not sure what you mean? We have this folder here https://github.com/Seagate/cortx/tree/main/doc/ova which lists all of the ova versions guides, you can identify which is the latest from the numbering. But maybe it is ok to keep it as it is now because then we don't have to change the directories at every release?

Please let me know what you think?

[stx-hseow]

Sorry I gave a wrong Pull Request link, I am referring to the Cortx on Open Virtual Appliance guide that is linked on the Cortx ReadMe (Get Started section).
On every new release, you would have to update the link in the ReadMe (Get Started section), so I thought wouldn't it better to have a consistent "latest" link that could be used?

[stx-hseow]

As you can see in another pull request, if the document Cortx on OVA updates on every release (1.0.4 / 2.0.0), it will cause many links to be broken on multiple files.

I did a quick check, apparently CONTRIBUTING.md / QUICK_START.md / README.md and few others within the doc/integrations folder are referring to the old link (1.0.4) instead of the newest link (2.0.0).

[novium258]

Aha, that makes sense. @johnbent what do you think?

[johnbent]

Yes, @hseow-seagate is exactly correct. His suggested approach is much better because it means that we won't break our documentation every time we create a new release.

[novium258]

SO the proposed solution would require - renaming the old document, then creating the new document with the old name whenever there is a new release?

[stx-hseow]

Yes, this is what I would suggest, currently we may have a duplicating link of both the "latest" and "PI-3" (Current latest) - so existing links don't break. But if this solution is adopted, future should not have duplicated links, and only archive (rename) when there is a new release.

[mukul-seagate11]

@hseow-seagate, https://github.com/Seagate/cortx/tree/main/doc/ova/1.0.4 is the OVA release documented for 1.0.4 so do not suggest to change the structure to avoid any break links.

Here is the latest OVA release for PI-3 in https://github.com/Seagate/cortx/tree/main/doc/ova/2.0.0/PI-3

[stx-hseow]

@mukul-seagate11 so the README, Contributing and Quick Start will have to always update for every new release then?

Also there are many integrations file (8 at the moment) linking to the old OVA guide (although for some, it would make sense to reuse the old version for consistency).

[mukul-seagate11]

@mukul-seagate11 so the README, Contributing and Quick Start will have to always update for every new release then?

Also there are many integrations file (8 at the moment) linking to the old OVA guide (although for some, it would make sense to reuse the old version for consistency).

yes, If there are any changes or structure changes

[stx-hseow]

would it not be better to not change them so other pull requests to those files won't have conflict due to url changes?

*Also saves some time (in managing the urls)?

[mukul-seagate11]

would it not be better to not change them so other pull requests to those files won't have conflict due to url changes?

*Also saves some time (in managing the urls)?

yes, you are correct & thats should be but if there are any design changes i.e. between 1.0.4 & 2.0.0 releases then accordingly the wiki instructions need to be changed.

[stx-hseow]

yes, you are correct & thats should be but if there are any design changes i.e. between 1.0.4 & 2.0.0 releases then accordingly the wiki instructions need to be changed.

I think that's very likely for all integrations (which we should retain specific version) but README, Contributing and Quick Start does not have any related instructions. I would believe that a persistent link would be better for those doc.

As for the integration files which require a version specific OVA Guide, we can create a placeholder file in the folder (e.g. ova/2.0.0/CORTX_on_Open_Virtual_Appliance.rst) that points to the ova/latest/CORTX_on_Open_Virtual_Appliance.rst. Once there is a new release, the file will then be replaced with the actual content instead of just a link to the latest guide.