Rename included ibm.spectrum_virtualize to ibm.storage_virtualize

[Andersson007]

Relates to ansible-collections/ansible-inclusion#65

The renaming process is described in README

For simplicity, assume that the next minor Ansible release is X.Y.0, and that collection foo.bar with latest release a.b.c has been renamed to baz.bam with latest release A.B.C.

• 1. baz.bam A.B.C must be compatible to foo.bar a.b.c up to renaming plugins. No options must be renamed without backwards compatible aliases, and no defaults or semantics changed.
• 2. baz.bam A.B.C can be added to Ansible X.Y.0.
• 3. A deprecation warning is added to Ansible X.Y.0's changelog (deprecated_features) that foo.bar has been renamed to baz.bam, that Ansible (X+1).0.0 will start having deprecated redirects from foo.bar to baz.bam, and that foo.bar will be removed from a later major release of Ansible.
• 4. A new release foo.bar (a+1).0.0 is made which contains no more content, but only deprecated redirects to baz.bam. Ideally it will have a dependency on baz.bam so that users that install foo.bar will have working deprecated redirects.
• 5. Ansible (X+1).0.0 contains both foo.bar (a+1).0.0, and either a baz.bam A.B'.C' release or a later major release that is still compatible with foo.bar a.b.c as specified in 1.
• 6. foo.bar will be dropped from Ansible (X+2).0.0 (needs to be announced in its changelog as removed_features).

[Andersson007]

Could anyone please add ibm.storage_virtualize to the appropriate release (so the next minor one i guess)?

[felixfontein]

I was just trying to implement that (see #307), when I noticed that they archived the old repository, so it will not be possible to implement step 4.

[gotmax23]

The maintainers can unarchive the old repository (Github lets you do that), complete step 4, and then archive it again if they so desire.

[Andersson007]

@felixfontein I've just unarchived it, thanks! Please let me know when I can archive it again

[felixfontein]

@Andersson007 I guess once a new major release has been released from that repository (and correctly tagged). That should happen after the Ansible 9 feature freeze though.

[Andersson007]

@felixfontein @gotmax23 thanks for your help!

[felixfontein]

Hmm, this shouldn't have been closed yet...

The next step is to create a new major version of the old collection, now that we had the Ansible 9 feature freeze, with content replaced by deprecated redirects.

[Andersson007]

@sumitguptaibm ^ could you please release the next major version of ibm.spectrum_virtualize:

1. Remove all tests and plugins
2. Add redirects similarly like in here (the version would be 10.0.0 in your case)
3. Release a major release of the collection and publish it on Galaxy. I don't know how you release the collection, but many use the process described in the releasing guidelines FWIW
4. Felix suggests also adding a changelog fragment with breaking_changes or major_changes entry for the redirects as for Ansible 2.9 users the redirects won't work

Many thanks to @felixfontein for the clarifications!

[sumitguptaibm]

Is this what you are looking for:

1. Remove everything from directories "tests" and "plugins". (What about "playbooks" directory? Should I leave it as it is?)
2. Do I need to add below for every module (I have 46 modules)?
   (a) I am not sure why warning_text for these 2 are different:
   rax_scaling_policy:
   deprecation:
   removal_version: 9.0.0
   warning_text: This module relies on the deprecated package pyrax.
   rhn_channel:
   deprecation:
   removal_version: 10.0.0
   warning_text: RHN is EOL, please contact the community.general maintainers
   if still using this; see the module documentation for more details.
3. We already have a new version with a different name. Do we need to release a new version with this collection's name and version as 3.0.0 (the last version was 2.0.0 where we mentioned that this is going to be depracated in this page https://github.com/ansible-collections/ibm.spectrum_virtualize bottom)?

[felixfontein]

What about "playbooks" directory? Should I leave it as it is?

Are these playbooks meant to be run with ansible-playbook -i ... ibm.spectrum_virtualize.foo? Or are these local examples/something else?

In the latter case, simply delete them. In the former case: good question. There is no redirect facility for playbooks so far. You could replace their tasks with a single ansible.builtin.fail task that informs that the new name should be used.

I am not sure why warning_text for these 2 are different:

The modules are deprecated for different reasons. The warning text should be set to something that makes sense for that specific module. For example, if module foo.bar.x is moved to baz.bam.y, it could say something like The module foo.bar.x has been renamed to baz.bam.y. Please update the references to the old name in your playbooks and roles..

We already have a new version with a different name. Do we need to release a new version with this collection's name and version as 3.0.0 (the last version was 2.0.0 where we mentioned that this is going to be depracated in this page https://github.com/ansible-collections/ibm.spectrum_virtualize bottom)?

The 2.0.0 collection does its deprecation only by README if I understood it correctly, which makes it basically invisible to most users. These should have bettern been properly deprecated by using meta/runtime.yml and deprecated: entries in the modules/plugins/etc. You can still do that in a 2.1.0 if you want.

You should definitely do the removal and replace by redirects in a 3.0.0 version. It's a breaking change, especially since you still support Ansible 2.9.

[sumitguptaibm]

Hi @Andersson007,
Just wanted to update that I have made most of the changes. I have a question too.
Should I delete text from README and other files (just leaving a text "deprecated" there, or I can leave them there?
changelog.yaml seems like one where I definitely cannot do this (as it contains all the history).

[felixfontein]

Leaving the README as-is (https://github.com/ansible-collections/ibm.spectrum_virtualize/blob/develop/README.md) seems fine to me.

[sumitguptaibm]

I am not able to create new tag (for creating new release) here. Is that something that can be enabled for me.

[Andersson007]

@sumitguptaibm you should create the tag locally on the release commit and then push it to upstream. Please follow the guide https://docs.ansible.com/ansible/devel/community/collection_contributors/collection_release_without_branches.html

[Andersson007]

@sumitguptaibm also i've just checked, you don't have the write/maintainer/or admin permissions in the repo. Please ask @Shilpi-J to give you the proper level of permissions. She's an admin in the repo.

[sumitguptaibm]

@Andersson007 , I got permissions for write. I have deleted the files. Would you like to check whether other changes are required, before I go ahead and put a tag of 3.0.0 with current code?

[Andersson007]

@sumitguptaibm hello, thanks for that and sorry for the delayed reply.
I don't see p. 2 from #306 (comment) is implemented.

[sumitguptaibm]

@Andersson007 , We added the redirects.

[Andersson007]

@felixfontein do you have an opportunity to take a quick look at the collection and confirm that @sumitguptaibm can proceed with p. 3 and 4 from the comment?

[felixfontein]

• There are no changelog fragments for major_changes or breaking_changes in the 3.0.0 changelog.
• ibm_svc_vdisk is deprecated with removal version 3.0.0, but it's not tombstoned, and the module does not exist in the collection. Changing https://github.com/ansible-collections/ibm.spectrum_virtualize/blob/develop/meta/runtime.yml#L6 to tombstone: is probably enough to fix this.
• The redirects in lines https://github.com/ansible-collections/ibm.spectrum_virtualize/blob/develop/meta/runtime.yml#L9-L100 are not deprecated. Please add deprecation: records so that the users get a message printed that they should adjust the FQCNs for the modules.

[felixfontein]

@sumitguptaibm there's still a lot to do here. Also this was supposed to be done for the Ansible 10 release (feature freeze was in May), so Ansible 10 now contains 2.0.0 instead of a collection having deprecated redirects.

[sumitguptaibm]

@felixfontein,
I have few questions:

1. Can you please let me know what other things we need to do other than what you mentioned on Jan 24th comment?
2. So far, I assume I have to add those redirects and then release another version 2.1.0 for this collection?
3. Should I redirect this to latest ansible version or to same version (i.e. 2.1.0) of new collection ibm.storage_virtualize?

[felixfontein]

Right now 2.0.0 does not contain any redirects, but still has the full content. So far there has been no release with the content removed and replaced by deprecated redirects. Removing content requires a new major release, so you need to do a 3.0.0 release; 2.1.0 would be a semantic versioning violation.

Can you please let me know what other things we need to do other than what you mentioned on Jan 24th comment?

Adressing them and releasing 3.0.0 should be sufficient.

[sumitguptaibm]

@felixfontein ,

1. Right now, I have to start process of releasing new collection ibm.storage_virtualize and its version is going to be 2.5.0.
   Do you mean that I should rather need to release 'new' collection's version 3.0.0?
   or
   Just release ibm.spectrum_virtualize version 3.0.0 (independent of version of new collection)?

2. Also, is this ok? ibm_svc_vdisk was deprecated previously (and replaced by ibm.storage_virtualize.ibm_svc_manage_volume ) and ibm_svc_auth module is redirected to new collection but same module name.
   Do I need to put 3.0.0 there instead?

---
requires_ansible: '>=2.9.0'
plugin_routing:
    modules:
        ibm_svc_vdisk:
            tombstone:
                removal_version: 2.0.0
                warning_text: Use ibm.storage_virtualize.ibm_svc_manage_volume instead.
        ibm_svc_auth:
            redirect: ibm.storage_virtualize.ibm_svc_auth
            deprecation:
                removal_version: 2.0.0
                warning_text: Use ibm.storage_virtualize.ibm_svc_auth instead.

3. I have checked-in the changes.
   Please let me know about above, and I'll do the needful.

[felixfontein]

1. Right now, I have to start process of releasing new collection ibm.storage_virtualize and its version is going to be 2.5.0.
   Do you mean that I should rather need to release 'new' collection's version 3.0.0?
   or
   Just release ibm.spectrum_virtualize version 3.0.0 (independent of version of new collection)?

It depends on what exactly you are doing in that release. You have to conform to semantic versioning (https://semver.org/).

2. Also, is this ok? ibm_svc_vdisk was deprecated previously (and replaced by ibm.storage_virtualize.ibm_svc_manage_volume ) and ibm_svc_auth module is redirected to new collection but same module name.
   Do I need to put 3.0.0 there instead?

For the tombstone 2.0.0 is kind of OK, since the module has been removed in 2.0.0. This is not 100% OK though, since technically this is a breaking change (if folks are using the collections keyword in playbooks), and thus must not be made in a minor release. It would be better to do this in a 3.0.0 release.

The deprecated redirects are NOT ok for a 2.5.0 release. The collection does not depend on the renamed collection, so this is a breaking change. Also the version 2.0.0 for removal of the deprecated redirects would be wrong anyway, since it must lie in the future.

[sumitguptaibm]

@felixfontein
My first question in connection with ibm.spectrum_virtualize. Let me rephrase if that helps:

1. We are definitely releasing old collection (ibm.spectrum_virtualize) with version 3.0.0
2. We are about to release new version of Ansible collection ibm.storage_virtualize (which we are thinking to be tagging as 2.5.0.). Will old (i.e. ibm.spectrum_virtualize) deprecation process be impacted by it?
   I am asking this because there will be no ibm.storage_virtualize version 3.0.0, , and with suggested change, we'll need to release a 3.0.0 of ibm.spectrum_virtualize. In that case, every package of ibm.spectrum_virtualize version 3.0.0 will be deprecated, but ibm.storage_virtualize won't have version 3.0.0 (it will have 2.5.0). Is that ok?