Omit deprecated commands from command help output

[landongrindheim]

What was the end-user or developer problem that led to this PR?

gem query was deprecated in rubygems 3.2. It was noted in #3984 that there should be a deprecation warning in the CLI (done in #4021) and a message in the guides.

A PR was opened to address the message (rubygems/guides#270) in Guides, but it was pointed out that the file being changed is auto-generated. This change leans into that auto-generation and should make rubygems/guides#270 redundant.

Closes #3984

What is your fix for the problem, implemented in this PR?

Add the deprecation note to the command's summary so that it can be relied upon for auto-generating the documentation. This note will display near the heading in the guides.

Make sure he following tasks are checked

• Describe the problem / feature
• Write tests for features and bug fixes
• Write code to solve the problem
• Make sure you follow the current code style and write meaningful commit messages without tags

[deivid-rodriguez]

I was reviewing this, but then I had a maybe better idea. What if, instead, we change the script in https://github.com/rubygems/guides/ to ignore deprecated commands and don't list them in the command reference section at all. I think, once we deprecate a command, it's no worth documenting it at all?

Thoughts?

[landongrindheim]

What if, instead, we change the script in https://github.com/rubygems/guides/ to ignore deprecated commands and don't list them in the command reference section at all. I think, once we deprecate a command, it's no worth documenting it at all?

@deivid-rodriguez This makes sense to me -- why hold the user's hand when the intent is to get them to stop using the functionality? I've poked around online for approaches to documenting deprecated functionality. This is what I've seen so far:

• Ruby stopped documenting Fixnum in v2.4 (It was present in v2.3)
• Ruby still documents safe_level as an argument to ERB.new, even though it was deprecated in v2.6
• ActiveRecord still documents update_attributes (with aliasing) even though it has been deprecated.
• Elixir documents the Behaviour module, noting that it has been deprecated.

You're doing the heavy lifting here, so I think you should feel free to choose the direction you'd like this to go 🙂

If this PR can be helpful, (say, adding **deprecated** to the summary instead of the newline which breaks functionality with gem help), please let me know and I'll adjust accordingly.

[deivid-rodriguez]

Thanks for the research! Yeah, that's exactly what I was thinking. If we intend users to stop using a command, not documenting it sounds like a good step in that direction.

The deprecation is removed altogether in favour of not rendering documentation for deprecated commands

I'd go with this one.

Should gem help commands be consistent with the guides and skip deprecated commands?

Yes, that's sounds like the right way forward to me.

Should there be mention of the deprecation anywhere other than in CLI output upon use?

I don't think so, just warning on usage and recommending alternatives seems fine to me.

[landongrindheim]

@deivid-rodriguez What do you think of this approach?

[deivid-rodriguez]

The approach looks good! Only added a couple of minor comments.

Could you squash everything into two commits, one that moves the description to the query command, and the other one that implements "removing" deprecated commands from help output?

[deivid-rodriguez]

Thanks so much for this fix and for your patience with my picky reviews 😃

[hsbt]

It's nice feature.