Document --only-group grouping strategy choice (#870)

The documentation says that parallel_test will attempt to use a runtime
grouping strategy if a runtime file is present and otherwise fall back
to the filesize strategy. This behavior can be overridden with an
explicit `--group-by` flag.

The `--only-group` flag changes this by always running with the filesize
strategy when no explicit strategy is given, even if a runtime file is
present. This behavior happens in `lib/parallel_tests/cli.rb:312`.

I was attempting to rely on the default behavior and also use the
`--only-group` flag and couldn't figure out why my runtime log wasn't
getting used. Only by reading the source did I figure out this
undocumented edge-case in the `--only-group` flag.

This commit adds explicit documentation about this. If you want to use
the `--only-group` flag and a runtime log, you _must_ explicitly set the
`--group-by` flag instead of relying on the default behavior.

CHANGELOG.md

@@ -8,6 +8,9 @@
 
 ### Added
 
+- Document unexpected behavior where the `--only-group` flag will also set a
+  grouping strategy.
+
 ### Fixed
 
 ## 4.2.0 - 2023-02-06

Readme.md

@@ -228,7 +228,9 @@ Options are:
                                        Process 1 will contain 1_spec.rb and 2_spec.rb
                                        Process 2 will contain 3_spec.rb
                                        Process 3 will contain all other specs
-        --only-group INT[,INT]
+        --only-group INT[,INT]       Only run the given group numbers. Note that this will force the 'filesize'
+                                     grouping strategy (even when the runtime log is present) unless you explicitly
+                                     set it otherwise via the '-group-by' flag.
     -e, --exec [COMMAND]             execute this code parallel and with ENV['TEST_ENV_NUMBER']
     -o, --test-options '[OPTIONS]'   execute test commands with those options
     -t, --type [TYPE]                test(default) / rspec / cucumber / spinach

lib/parallel_tests/cli.rb

@@ -244,7 +244,15 @@ def parse_options!(argv)
           TEXT
         ) { |groups| options[:specify_groups] = groups }
 
-        opts.on("--only-group INT[,INT]", Array) { |groups| options[:only_group] = groups.map(&:to_i) }
+        opts.on(
+          "--only-group INT[,INT]",
+          Array,
+          <<~TEXT.rstrip.split("\n").join("\n#{newline_padding}")
+            Only run the given group numbers. Note that this will force the 'filesize'
+            grouping strategy (even when the runtime log is present) unless you explicitly
+            set it otherwise via the '-group-by' flag.
+          TEXT
+        ) { |groups| options[:only_group] = groups.map(&:to_i) }
 
         opts.on("-e", "--exec [COMMAND]", "execute this code parallel and with ENV['TEST_ENV_NUMBER']") { |arg| options[:execute] = Shellwords.shellsplit(arg) }
         opts.on("-o", "--test-options '[OPTIONS]'", "execute test commands with those options") { |arg| options[:test_options] = Shellwords.shellsplit(arg) }