* [PATCH] FAQ: Explain how to binary search one's dotfiles
@ 2020-05-07 21:23 Daniel Shahaf
0 siblings, 0 replies; only message in thread
From: Daniel Shahaf @ 2020-05-07 21:23 UTC (permalink / raw)
Feedback is welcome. I've stared at the text for too long to be able to
find any bugs it may have remaining.
myeit() creates a numbered list. (The "eit" stand for "enumerated
items", I guess.)
Etc/FAQ.yo | 105 +++++++++++++++++++++++++++++++++++++++++++++++--
Util/zyodl.vim | 6 ++-
2 files changed, 107 insertions(+), 4 deletions(-)
diff --git a/Etc/FAQ.yo b/Etc/FAQ.yo
index d1f8b7d83..afc01b2bc 100644
@@ -49,16 +49,22 @@ def(item)(2)(
+COMMENT(TODO: make this expand to a Unicode em dash (U+2014) in HTML output)\
myreport(Z-Shell Frequently-Asked Questions)(Peter Stephenson)(2010/02/15)
COMMENT(-- the following are for Usenet and must appear first)\
mydit(Submitted-By:) email(firstname.lastname@example.org (Peter Stephenson))
-mydit(Copyright:) (C) P.W. Stephenson, 1995--2016 (see end of document)
+mydit(Copyright:) (C) P.W. Stephenson, 1995--2020 (see end of document)
This document contains a list of frequently-asked (or otherwise
@@ -150,6 +156,7 @@ Chapter 6: The future of zsh
6.2. Where do I report bugs, get more info / who's working on zsh?
6.3. What's on the wish-list?
6.4. Did zsh have problems in the year 2000?
+6.5. When reporting a bug, how do I reduce my mytt(.zshrc) into a minimal reproduction recipe?
@@ -2527,6 +2534,98 @@ sect(Did zsh have problems in the year 2000?)
show problems here.
+sect(When reporting a bug, how do I reduce my mytt(.zshrc) into a minimal reproduction recipe?)
+ When reporting a bug, the gold standard is to include with the bug
+ a myem(minimal reproduction recipe), with which anyone who reads the bug
+ report can url(reproduce the bug for themselves)
+ at will.
+ When you run into a bug in the shell, particularly during interactive
+ use, a reproduction recipe would ideally start by running tt(zsh -f)
+ and then, within that instance of the shell, run a minimal short
+ sequence of commands that reproduces the bug. A good way to devise
+ such recipes is the following:
+COMMENT(For reference, here's Vim's write-up of a similar process:
+ myeit() First, ensure the bug is reproducible. To do this, start
+ a new instance of the shell emdash() for example, open a new tab in
+ your terminal emulator emdash() and reproduce the bug there.
+ myeit() Start a new instance of the shell by running the
+ command mytt(zsh -f) from your regular shell prompt, and reproduce the
+ bug there. (The mytt(-f) flag inhibits mytt(.zshenv),
+ mytt(/etc/zprofile), mytt(.zprofile), mytt(/etc/zshrc), and
+ mytt(.zshrc) from being sourced.)
+ If you succeeded in reproducing the bug in mytt(zsh -f), copy the
+ commands you used and their outputs (from the mytt(zsh -f) invocation
+ to the point the bug occurred) and include them in your bug report.
+ Skip the remaining steps of this procedure.
+ If, however, the bug happens in your regular shell but not in mytt(zsh
+ -f), read the next steps.
+ myeit() Make a backup of your tt(.zshrc) file.
+ myeit() Delete your tt(.zshrc) file, start a new shell, and confirm
+ that the problem does em(not) reproduce there. (If the problem
+ does reproduce there, it's caused by something in mytt(.zshenv),
+ mytt(.zprofile), mytt(/etc/zprofile), or mytt(/etc/zshrc), so apply
+ this procedure from the top to those files rather than to your
+ COMMENT(Note that mytt(/etc/zshenv) is not mentioned, since by this
+ point we have established the bug does not occur under mytt(zsh -f),
+ which sources mytt(/etc/zshenv).)
+ COMMENT(mytt(.zlogout) and mytt(/etc/zlogout) aren't mentioned because
+ they're unlikely to be relevant to most readers.)
+ myeit() At this point, you know that the problem is caused by
+ something in your mytt(.zshrc) file, but not what line exactly.
+ To find the responsible line, we will use
+ a url(variation)(https://en.wikipedia.org/wiki/Delta_debugging)
+ of the url(binary search)(https://en.wikipedia.org/wiki/Binary_search)
+ algorithm, as follows:
+ Suppose your mytt(.zshrc) file has 200 lines. To start, copy
+ the em(first) half of your mytt(.zshrc) emdash() that is, lines
+ 1 through 100 emdash() from the backup copy to your live mytt(.zshrc)
+ file, and check whether the bug reproduces then. Now, empty the live
+ mytt(.zshrc) file again, and copy the em(second) half of your
+ mytt(.zshrc) file from the backup to the live mytt(.zshrc) file
+ emdash() the live file should now contain lines 101 through 200, only
+ emdash() and see whether the problem reproduces.
+ Normally, the bug will reproduce em(either) with lines 1 through 100
+ em(or) with lines 101 through 200, but not in both cases. To isolate
+ the specific line that causes the bug, repeat the above process on the
+ relevant half of the file: for example, if you've determined that the
+ bug reproduces when only lines 101 through 200 are installed, check
+ whether the bug reproduces (a) when only lines 101 through 150 are
+ installed, and (b) when only lines 151 through 200 are installed.
+ Repeat the process until the resulting mytt(.zshrc) is minimal.
+ It is not important to break the file into two halves exactly.
+ Breaking the file into two parts sized one-third and two-thirds, for
+ example, will work equally well. You can even try restoring one line
+ at a time, but this is impractical for all but the shortest
+ mytt(.zshrc) files.
+ myeit() Include the minimal set of lines you devised in the previous
+ step, along with the commands you used and their outputs, in your bug
+ myeit() Restore your mytt(.zshrc) from backup.
+ Bug reports should be emailed to the mytt(email@example.com) public
+ mailing list; see link(6.2)(62) for details.
Thanks to zsh-list, in particular Bart Schaefer, for suggestions
@@ -2542,7 +2641,7 @@ Wischnowsky).
This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997,
-1998, 1999, 2000, 2012. This text originates in the U.K. and the author
+1998, 1999, 2000, 2012, 2020. This text originates in the U.K. and the author
asserts his moral rights under the Copyrights, Designs and Patents Act,
diff --git a/Util/zyodl.vim b/Util/zyodl.vim
index 73cd027fd..db92de590 100644
@@ -79,7 +79,8 @@ syn match zyodlSpecial "\<DASH()-" conceal cchar=—
syn match zyodlSpecial "+\?LPAR()" conceal cchar=(
syn match zyodlSpecial "+\?RPAR()" conceal cchar=)
syn match zyodlSpecial "+\?PLUS()" conceal cchar=+
+syn match zyodlFAQDash "+\?\<emdash()" conceal cchar=—
"" Highlight groups:
hi def link zyodlTt Constant
hi def link zyodlVar Identifier
@@ -98,6 +99,9 @@ hi def link zyodlRef Include
hi def link zyodlSItemArg1 Macro
hi def link zyodlSItemArg2 Underlined
+"" Derived highlighting groups:
+hi def link zyodlFAQDash zyodlSpecial
let b:current_syntax = "zyodl"
let &cpo = s:cpo_save
^ permalink raw reply [flat|nested] only message in thread
only message in thread, back to index
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-07 21:23 [PATCH] FAQ: Explain how to binary search one's dotfiles Daniel Shahaf
Archives are clonable: git clone --mirror http://inbox.vuxu.org/zsh-workers
Example config snippet for mirrors
Newsgroup available over NNTP:
AGPL code for this site: git clone https://public-inbox.org/public-inbox.git