The future of zsh
================================================================================

.. _faq-known-bugs:
What bugs are currently known and unfixed? (Plus recent important changes)
--------------------------------------------------------------------------------

Bugs tend to be tracked on the zsh-workers mailing list; see the
next section.  Check the mailing list to see if a bug has been
reported.  (There is a bug tracker at the zsh development site
at Sourceforge, but it's not in active use.)

To see how recent versions of the shell have changed, look at
the README file in the source distribution.  This indicates the
most important changes, and in particular draws attention to
incompatibilities you might notice.

.. _faq-report-bugs:
Where do I report bugs, get more info / who's working on zsh?
--------------------------------------------------------------------------------

The shell is being maintained by various (entirely self-appointed)
subscribers to the mailing list,

.. code-block:: zsh
   :class: example

      zsh-workers@zsh.org

so mail on any issues (bug reports, suggestions, complaints...)
related to the development of the shell should be sent there.  If
you want someone to mail you directly, say so.  Most patches to zsh
appear there first.

Please note when reporting bugs that many exist only on certain
architectures, which the developers may not have access to.  In
this case debugging information, as detailed as possible, is
particularly welcome.

Two progressively lower volume lists exist, one with messages
concerning the use of zsh,

.. code-block:: zsh
   :class: example

      zsh-users@zsh.org

and one just containing announcements:  about releases, about major
changes in the shell, or this FAQ, for example,

.. code-block:: zsh
   :class: example

      zsh-announce@zsh.org

(posting to the last one is currently restricted).

Finally, there is a private mailing list (the general public cannot subscribe
to it) for discussing bug reports with security implications, i.e., potential
vulnerabilities: ``zsh-security@zsh.org``.  If you find a security problem
in zsh itself, please mail this address.

Note that you should only join one of these lists:  people on
zsh-workers receive all the lists, and people on zsh-users will
also receive the announcements list.

The lists are handled by an automated server.  The instructions for
zsh-announce and zsh-users are the same as for zsh-workers: just
change zsh-workers to whatever in the following.

To join zsh-workers, send email to

.. code-block:: zsh
   :class: example

      zsh-workers-subscribe@zsh.org

(the actual content is unimportant).  Replace ``subscribe`` with
``unsubscribe`` to unsubscribe.  The mailing software (``Sympa``) has
various bells and whistles: you can retrieve archived messages.
Mail `sympa@zsh.org?subject=help <mailto:sympa@zsh.org?subject=help>`_ for detailed information.
Administrative matters are best sent to
`zsh-workers-owner@zsh.org <mailto:zsh-workers-owner@zsh.org>`_.

Note that this location changed in August 2020, and the
instructions to go with it are slightly different.

An archive of mailings for the last few years can be found at
  `http://www.zsh.org/mla/ <http://www.zsh.org/mla/>`_
at the main zsh archive site.

What's on the wish-list?
--------------------------------------------------------------------------------

The code bears the marks of the ages and many things could be done much
better with a rewrite.  A more efficient set of code for
lexing/parsing/execution might also be an advantage.  Volunteers are
particularly welcome for these tasks.

Some future possibilities which have been suggested:
    
    *  The shell, in particular the line editor, should support Unicode
       characters.  Initial support for this appeared in version 4.3;
       it is reasonably complete in the line editor but patchy elsewhere
       (note this may require the configuration option --enable-multibyte).
    *  The parameter code could do with tidying up.
    *  Configuration files to enable zsh startup files to be created
       with the Dotfile Generator.
    *  Further improvements in integrating the line editor with shell
       functions.
    

Did zsh have problems in the year 2000?
--------------------------------------------------------------------------------

Not that I heard of; it's up to you to be careful with two-digit dates,
though, which are produced by the prompt escapes ``%W`` and ``%D``,
and also by the command ``print -P``.  Earlier versions of zsh may
show problems here.

When reporting a bug, how do I reduce my ``.zshrc`` into a minimal reproduction recipe?
--------------------------------------------------------------------------------

When reporting a bug, the gold standard is to include with the bug
a :emphasis:`minimal reproduction recipe`, with which anyone who reads the bug
report can `reproduce the bug for themselves <https://www.chiark.greenend.org.uk/~sgtatham/bugs.html#showmehow>`_
at will.

When you run into a bug in the shell, particularly during interactive
use, a reproduction recipe would ideally start by running ``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:

    
    #.  First, ensure the bug is reproducible.  To do this, start
    a new instance of the shell --- for example, open a new tab in
    your terminal emulator --- and reproduce the bug there.
    
    #.  Start a new instance of the shell by running the
    command ``zsh -f`` from your regular shell prompt, and reproduce the
    bug there.  (The ``-f`` flag inhibits ``.zshenv``,
    ``/etc/zprofile``, ``.zprofile``, ``/etc/zshrc``, and
    ``.zshrc`` from being sourced.)
    
    If you succeeded in reproducing the bug in ``zsh -f``, copy the
    commands you used and their outputs (from the ``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 ``zsh
    -f``, read the next steps.
    
    #.  Make a backup of your ``.zshrc`` file.
    
    #.  Delete your ``.zshrc`` file, start a new instance of zsh, and confirm
    that the problem does :emphasis:`not` reproduce there.  (If the problem
    does reproduce there, it's caused by something in ``.zshenv``,
    ``.zprofile``, ``/etc/zprofile``, or ``/etc/zshrc``, so apply
    this procedure from the top to those files rather than to your
    ``.zshrc``.)
    
    
    
    #.  At this point, you know that the problem is caused by
    something in your ``.zshrc`` file, but not what line exactly.
    To find the responsible line, we will use
    a `variation <https://en.wikipedia.org/wiki/Delta_debugging>`_
    of the `binary search <https://en.wikipedia.org/wiki/Binary_search>`_
    algorithm, as follows:
    
    Suppose your ``.zshrc`` file has 200 lines.  To start, copy
    the :emphasis:`first` half of your ``.zshrc`` --- that is, lines
    1 through 100 --- from the backup copy to your live ``.zshrc``
    file, and check whether the bug reproduces then.  Now, empty the live
    ``.zshrc`` file again, and copy the :emphasis:`second` half of your
    ``.zshrc`` file from the backup to the live ``.zshrc`` file
    --- the live file should now contain lines 101 through 200, only
    --- and see whether the problem reproduces.
    
    Normally, the bug will reproduce :emphasis:`either` with lines 1 through 100
    :emphasis:`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 ``.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
    ``.zshrc`` files.
    
    #.  Include the minimal set of lines you devised in the previous
    step, along with the commands you used and their outputs, in your bug
    report.
    
    #.  Restore your ``.zshrc`` from backup.
    

Bug reports should be emailed to the ``zsh-workers@zsh.org`` public
mailing list; see :ref:`faq-report-bugs` for details.
