Removing old/stale scenario guides

We’ve had scenario guides on the main documentation for some time now, but many of them are unmaintained. Three already moved to their respective collections, but we have 13 more that are just lingering in the following categories:

I’m proposing the following:

  1. Open an issue in the collection related to the scenario guide to ask them to move the content into their collection. Let them know the stale content will be removed in Ansible 10.
  2. Remove them all in devel branch and replace with a stub page that either points to the new location within the collection, or the collection issue we created above so readers know where to go for feedback etc. This sets us up for their removal when Ansible 10 releases.

Since we’re creating all the collection-level issues, we’ll know if the content has been moved and can update the stub with the correct pointer to the new location.

This has the benefit of removing stale documentation and hopefully convincing collection owners to take this content over and update it to match their updated collection.

Would welcome feedback on this idea before we implement it.

1 Like

Is there a difference between collections that are included in the community package and those that are not?

What I mean is: Can we get rid of scenario guides for collections that are not part of Ansible 9 easier?

BTW vmware.vmware_rest seems to have the scenario guides in the collection repository. But the official documentation looks weird. Shouldn’t this be a link to Scenario Guide or VMware Guide (REST)?

I agree that if it isn’t in the package, it should be removed (scenario guide). As for vmware.vmware_rest - looks like the :ref: is busted on that page. It should link to the latter above.

Didn’t we do that once?

In any case, :+1: for getting rid of the ones still there!

Yes we did and some of them got ignored. I will check to see if there is an issue already before creating a new one. I saw one that was not only ignored, but they also ignored a PR someone here did for them to move it. so :person_shrugging:t2:

That’s really sad!

In that case… these scenario guides seem to be about collections that are not part of the Ansible community package:

Please check if I’m right. If I am, I’d say just remove them completely.

Should I try to fix this, or do you prefer to remove the VMware REST Scenarios completely? Since the link is broken (and probably has been for some time) I tend to remove it.

@felixfontein Guide, Rackspace Cloud Guide and Scaleway Guide seem to be about modules that are now in community.general. Could you please have a look and check if I’m right? And, if I am, think about what we should do with them?

@samccann Your proposal sounds reasonable, but I think these scenario guides are low hanging fruit and we can do something about them pretty easily. And then we can think what to do with the rest.

This one is strange. It doesn’t mention any collection, and two of the three modules mentioned have never been part of Ansible, while the third is part of community.general.

I would recommend to delete that guide, as it contains incorrect information.

That collection was part of Ansible, but got removed. The guide should be moved there, assuming it is still relevant. If it is no longer relevant, it should be removed.

This one belongs to oracle.oci_ansible_modules and should be part of that collection.

I guess it makes sense to move them to community.general, but they clearly need an overhaul. They mention dynamic inventory scripts, for example, that are now in GitHub - ansible-community/contrib-scripts: Old Ansible inventory & vault scripts.

The Rackspace modules are currently deprecated in community.general since the Python library they use is deprecated. They will be removed in the next major community.general release. It’s probably best to simply delete that scenario guide.

1 Like

Looks like I was wrong there, is still part of the package. We’ve canceled the removal.

Oh right, we cancelled the removal. But in any case, it should be moved to the collection, and removed from

@felixfontein I’ve created PR 965 for a start. Let’s see what @samccann thinks about it.

1 Like

The Alicloud guide already got moved here: That collection doesn’t seem to exist on Galaxy though.

I’m currently adding another copy of it to community.general, since that collection still contains some modules.

PR: Add Alicloud, Packet, and Scaleway scenario guides by felixfontein · Pull Request #7714 · ansible-collections/community.general · GitHub

Add stubs for moved scenario guides

True, but I don’t think we should wait on them moving the guide to their collection. However, I’ve opened an issue in their repo to inform them.

But since this collection isn’t part of the ansible package, I think we should just remove the scenario guide.

Anyway, they’re informed now and can move it to their collection if they want.


I just noticed that the Online guide also belongs into community.general since the Online modules and inventory plugin live there. I’ve added it to Add Alicloud, Packet, and Scaleway scenario guides by felixfontein · Pull Request #7714 · ansible-collections/community.general · GitHub.

Add Guide stub

1 Like

Thanks @mariolenz and @felixfontein this is great!

My one question - on the PR that removes the guides (or adds stub pages). My initial thought was that only goes into devel, but that means for the guides @felixfontein is revamping in community.general - users won’t see that until Ansible 10. Is that okay or should we separate the ‘delete now’ guides from the ‘stub pages to new location’ guides? The latter could be backported to stable-2.16 and available in Ansible 9 on the next community.general release that picks up the new guides.

I personally think we can just keep all the changes in devel and they would become /latest/ with Ansible 10, but figured I’d ask.

I created Remove/relocate stale scenario guides · Issue #969 · ansible/ansible-documentation · GitHub to track all the moves/removals. I’ll update that now with the two PRs mentioned here (for removal and the moves to community.general).

I tend to keep it simple and only remove the scenario guides from devel, even if it means that the stub pages linking to the new locations won’t show up until Ansible 10.

But I’m open to split my PR into two new ones if you think it better.