Fix problem with Open3.popen3 where confirm_documentation task never finishes waiting for child processes

[ydah]

see: https://github.com/rubocop/rubocop-rspec/actions/runs/11360936578/job/31599655573

This PR is composed of the following three commits:

1. Fix problem with Open3.popen3 where confirm_documentation task never finishes waiting for child processes 799df91

It freezes at confirm_documentation as follows:

❯ bundle exec rake confirm_documentation
Files:         123
Modules:        16 (    3 undocumented)
Classes:       116 (    0 undocumented)
Constants:     191 (  191 undocumented)
Attributes:      1 (    0 undocumented)
Methods:       321 (  252 undocumented)
 30.85% documented
* generated /Users/ydah/rubocop-rspec/docs/modules/ROOT/pages//cops_rspec.adoc

The documentation for Open3.popen3 described the following:

Refs: https://www.rubydoc.info/stdlib/open3/Open3.popen3

You should be careful to avoid deadlocks. Since pipes are fixed length buffers, Open3.popen3("prog") {|i, o, e, t| o.read } deadlocks if the program generates too much output on stderr. You should read stdout and stderr simultaneously (using threads or IO.select). However, if you don’t need stderr output, you can use Open3.popen2. If merged stdout and stderr output is not a problem, you can use Open3.popen2e. If you really need stdout and stderr output as separate strings, you can consider Open3.capture3.

Perhaps, but the following deadlock conditions were present.

• Child process: It was waiting to write beyond the buffer size to stderr output.
• Parent process: Waiting for the pipe to which the standard output of the child process was to be closed.

2. Improve confirm_documentation task to display out-of-sync documentation e6ccc37

This is a change to output what is the difference when the confirm_documentation task fails and prompts you to run rake generate_cops_documentation but you have not made any changes that affect the documentation.
I actually got confused when using ruby 3.4.0dev because I forgot that the hash format had changed as follows
https://github.com/rubocop/rubocop-rspec/pull/1974/files

3. bundle exec rake generate_cops_documentation 9e2ecd9

This is a change that only updates the documentation. using rake generate_cops_documentation
Without this, CI will fail.

---

Before submitting the PR make sure the following are checked:

• Feature branch is up-to-date with master (if not - rebase it).
• Squashed related commits together.
• Added tests.
• Updated documentation.
• Added an entry to the CHANGELOG.md if the new code introduces user-observable changes.
• The build (bundle exec rake) passes (be sure to run this locally, since it may produce updated documentation that you will need to commit).

If you have created a new cop:

• Added the new cop to config/default.yml.
• The cop is configured as Enabled: pending in config/default.yml.
• The cop is configured as Enabled: true in .rubocop.yml.
• The cop documents examples of good and bad code.
• The tests assert both that bad code is reported and that good code is not reported.
• Set VersionAdded: "<<next>>" in default/config.yml.

If you have modified an existing cop's configuration options:

• Set VersionChanged: "<<next>>" in config/default.yml.

[bquorning]

I think I need some more explanation of each commit in this PR.

[ydah]

@bquorning Updated PR description. How do you like it?

[ydah]

memo) Perhaps without this support, the CI / Confirm config and documentation (pull_request) job for all PRs will not be completed, so the merge will not be possible.

[bquorning]

I didn’t know about the deadlock problem with popen3, but it makes perfect sense now that you mention it.

There’s a few problems with your PR (stdin is in fact stdout, and we get a status object returned, not a process – which means we can call #success? on it.

I would also suggest that we don’t raise at the end of the task, but just exit with an error status.

[pirj]

One nitpick

Thank you!

I yet to dive into the pr description to understand why this suddenly started happening in the first place

[bquorning]

why this suddenly started happening in the first place

We run out of IO buffer and deadlock the process when there are too many errors.

[bquorning]

But yes, why did the task suddenly start failing? Did something change in rubocop master branch?

[ydah]

But yes, why did the task suddenly start failing? Did something change in rubocop master branch?

I think it's because the following change made the header links to be output, and there were a lot of diffs for git diff --exit-code docs/. These diffs are stacked in IO.

• rubocop/rubocop@2e6254f

[pirj]

Thank you! ❤️