cmd/benchstat: add example benchmarking workflow to package comment

Author: nsajko

cmd/benchstat/README.md

@@ -79,19 +79,49 @@
 //	name        time/op
 //	GobEncode   13.6ms ± 1%
 //	JSONEncode  32.1ms ± 1%
-//	$
 //
 // If run with two input files, benchstat summarizes and compares:
 //
 //	$ benchstat old.txt new.txt
 //	name        old time/op  new time/op  delta
 //	GobEncode   13.6ms ± 1%  11.8ms ± 1%  -13.31% (p=0.016 n=4+5)
 //	JSONEncode  32.1ms ± 1%  31.8ms ± 1%     ~    (p=0.286 n=4+5)
-//	$
 //
 // Note that the JSONEncode result is reported as
 // statistically insignificant instead of a -0.93% delta.
 //
+// An example benchmarking workflow in Unix shell language:
+//
+//	oldBin=/tmp/benchmarkBinaryOld
+//	newBin=/tmp/benchmarkBinaryNew
+//	old=/tmp/benchmarkReportOld
+//	new=/tmp/benchmarkReportNew
+//	result=/tmp/benchstatReport
+//	
+//	# Create first test executable.
+//	go test -c -o "$oldBin" -bench .
+//	
+//	# Apply code patch now
+//	git checkout fixes
+//	
+//	# Create the other test executable.
+//	go test -c -o "$newBin" -bench .
+//	
+//	# Test and benchmark.
+//	for i in 0 1 2 3 4 5 6 7 8 9 10 11 12 13; do
+//		printf 'Tests %s starting.\n' "$i"
+//		"$oldBin" -test.bench . >> "$old"
+//		"$newBin" -test.bench . >> "$new"
+//	done
+//	
+//	# Create final report with benchstat.
+//	benchstat "$old" "$new" > "$result"
+//
+// Possible variations include disabling tests (done with the command
+// line arguments "-run -"), running three instead of two benchmark
+// executables in the loop or increasing niceness or, even better,
+// running the binaries under a real time scheduling policy (see
+// sched_setscheduler and SCHED_FIFO).
 package main
 
 import (