44TUGboat, Volume 39 (2018), No. 1

New rules for reporting bugs in theLATEX core software(as maintained by the LATEX Project)Frank Mittelbach and The LATEX Project Team
Abstract
Software has bugs and LATEX unfortunately is no
exception. If somebody encounters a bug then it
helps if that bug gets reported to the right people
so that the bug can be resolved (or a workarounddocumented or whatever is most appropriate). The
problem is to know to whom to report the bug. For
this the latexbug package has been developed tohelp in addressing the right group of maintainers.
The LATEX Project Team maintains a bug database for its own code base (which consists of theLATEX kernel and some packages that have been written by people in the LATEX Project Team).
In this article we describe how to report bugsin the core LATEX software or search through alreadyknown issue reports in that database. The article
also explains where to find the development versionof LATEX if that ever becomes necessary.
Thank you for taking the time to report a bugand prepare a test file showing it!
Contents1

The LATEX kernel sources
1.1 A note on Git pull requests . . . . .

44
44

2

Policy on layout and interface deficiencies

443The LATEX bug database

45

4The latexbug package
4.1 The user interface . . . . . . . . . .
4.2 Bugs in latexbug itself . . . . . . .

45
45
46

5

Important links

46

1

The LATEX kernel sources

LATEX (or more precisely LATEX 2ε , the current standard) is part of every major TEX distribution, e.g.,
TEX Live, MiKTEX, or MacTEX to name a few. The
official releases of LATEX are all published on CTAN(the Comprehensive TEX Archive Network) where
they can be downloaded if necessary and from there
they usually find their way into the major distributions within a few days.
Until recently the LATEX Project Team has maintained the development version of LATEX 2ε in an SVNFrank Mittelbach and The LATEX Project Team(Subversion) repository with read-only access for thepublic from the LATEX Project website. We have now
switched to a Git repository1 located athttps://github.com/latex3/latex2eand from that browser page you can explore the files
in the development version.
If necessary, the most recent (unreleased) development version can be downloaded from there in a.zip archive (roughly 25Mb) by using the appropriate button. If you are familiar with Git or SVN you
can also clone the repository using the command lineor your favorite Git frontend tool or alternatively doa checkout using an SVN tool.
1.1

A note on Git pull requests

Git repositories (somewhat in contrast to SVN ones)
support widely distributed development and allow
people to provide change sets that are made available
through so-called pull requests, so that the maintainers of a program can “pull the suggested changes”
into the main repository.
While we appreciate contributions, we thinkthat for the core LATEX software pull requests areusually not a good approach (unless the change has
been previously discussed and agreed upon).
The stability of LATEX is very important and thismeans that changes to the kernel are necessarily very
conservative. It also means that a lot of discussion
has to happen before any changes are made. So if
you do decide to post a pull request, please bear thisin mind: we do appreciate ideas, but cannot always
integrate them into the kernel and it is quite likelythat we will have to reject updates made in this way.
If you want to discuss a possible contribution
before (or instead of) making a pull request, wesuggest you raise the topic first on the LATEX-L list
(see links below) or drop a line to the team.
2

Policy on layout and interface
deficiencies

Up front we should probably stress that “deficiencies” in the design of the standard document classes(article, report and book) as well as questionable
but long established interface behavior of commands
are things that we will normally not change, even if
we can all agree that a different behavior or a different layout would have been a better choice. You
are, of course, welcome to report issues in these areas, using the procedure explained below, but in all
likelihood such reports will get suspended.
1 Please note, that if you have previously bookmarked theold SVN repository you should update that bookmark to thenew Git repository as the SVN repository is frozen and nolonger up-to-date and will soon vanish!

TUGboat, Volume 39 (2018), No. 1
The reason is that the kernel interfaces and thedocument classes have been used for many years inessentially all documents (even documents using different classes; these are often built upon the standard
classes in the background) and thus such changes
would break or at a minimum noticeably changenearly all existing documents.
3

The bug database for the LATEX kerneland core packages

Throughout the last two decades the LATEX Project
Team has maintained a bug database using GNATS,a free software system from the FSF. While thishas served us well in the past, it has its problems
and with our move to Git-based source control its
workflow no longer fits. We have therefore decided
to switch to a new tracking system and the natural
choice was to use the one already provided as part of
the GitHub setup (the place where the sources are
now hosted), namely the Issue Tracker.
Unfortunately, it is not possible for a number ofreasons to automatically transfer the old bug reports
to the new system so we are in a slightly awkward
position that we have old bugs in one system andthe new ones in another. Thus for searching throughalready reported bugs it is necessary to search twosystems:• GNATS for bugs reported before 2018;• The Github Issue Tracker for LATEX 2ε for bugs
reported in 2018 and later.
Over time we hope that the bugs listed in GNATS
will all be only of historical interest, but right now it
is probably helpful to look in both places (see linksbelow) — sorry for that.
4The latexbug package

So far we have talked about where to find the core
LATEX software and how to report issues with it. However, the LATEX universe consists of several thousand
contributed packages maintained by individuals allover the world. And if a bug happens in one of thosepackages it doesn’t help anybody if it is dumped at
the LATEX Project’s doorstep.
For one, we can’t actually change other people’s
code even if we are able to identify the issue. Furthermore we are only a few people and simply do
not have the bandwidth to analyze bugs in otherpeople’s work.
We have therefore written this little package
called latexbug that should help in identifying therightful addressee for a bug report. We ask that it
be loaded in any test file intended to be sent to theLATEX bug database as part of a bug report.

45The package will determine if the test file is ina suitable state to be sent to us or if it should be
modified first or if it should be sent to somebody
else because the bug is (likely) to be in code notmaintained by the LATEX Project Team.
Bug reports sent to the LATEX bug database
without that prior verification are likely to get closed
without being looked at at our end in the future.
4.1

The user interface

The interface is simple: the package has no options
and doesn’t define any new commands to be used.
All that is required is that the package be loaded
as the very first step in the test file that shows
the bug — in other words, before the line loadingthe \documentclass. For that reason it must beloaded using \RequirePackage instead of the usual\usepackage declaration that is used in the preambleof a document.
Thus, a bug report test file should look like this:\RequirePackage{latexbug}\documentclass{article}% preamble as necessary% (drop anything not needed, please)\begin{document}% example showing the bug% (as short and concise as possible)\end{document}
Of course, instead of article you may need to loada different standard class, but do not load a thirdparty class as we can’t accept a bug that manifests
itself only when using a class we don’t maintain.
If the test file runs through (showing the bug)without any complaints for latexbug then the test
file is ready to be sent to the LATEX bug database.
The procedure for uploading and the location is documented athttps://www.latex-project.org/bugs/
If latexbug does generate an error, however, thenthis error needs to be addressed first and then, depending on the resolution, the bug report may haveto be sent to somebody else.
An error is generated if the test file makes use ofthird-party code that is not maintained by the LATEX
Project Team. For example, if your test document
loads array, geometry, footmisc and hyperref you
would see the following:
Package latexbug Error: Third-party file(s)New rules for reporting bugs in the LATEX core softwareThis test file uses third-party file(s)==============geometry.sty -> Hideo Umeki(as maintained by the LATEX Project)

46

TUGboat, Volume 39 (2018), No. 1<latexgeometry [at] gmail [dot] com>footmisc.sty
hyperref.sty -> Heiko Oberdiek
https://github.com/ho-tex/hyperref/issues==============
The array package is accepted as it is one of the corepackages maintained by the LATEX Project team but
the other three are not. For geometry and hyperref
we have maintainer info available, so we provide that,
whereas for footmisc this information is missing.
Thus, in that case you have to search for it yourself,
if it turns out that the bug is related to that package.
The latexbug package then continues with advice to remove such third-party code from the file:
So you should contact the authorsof these files, not the LaTeX Team!
(Or remove the packages that loadthem, if they are not necessary toexhibit the problem).
If that is not possible, because the bug goes away
if a package is removed, then the problem is (mostlikely) with this package and the bug report should
be sent to the maintainer of that package and not to
the LATEX bug database.
To make life somewhat easier, latexbug will tell
you the name of the maintainer (if we know it andhave added it) and if possible also the canonical bug
address for the package (as in the cases of geometry
and hyperref). If we don’t have that information,
you need to find it out for yourself by looking at thepackage documentation.
There may be cases where third-party code isessential to exhibit a bug in core LATEX code maintained by the LATEX Team. The error text therefore
finishes off with the following sentence:
If you think the bug is in core LaTeX(as maintained by the LaTeX Team) but
these files are needed to demonstrate
the problem, please continue and mention
this explicitly in your bug report.
Please explain in detail your reasoning why you think
this is the case as part of the bug report.
4.2

Bugs in latexbug itself

When a document is run through LATEX it will load
a number of files, and bug reports that are to besent to the LATEX Team should only load files that
we maintain and not third-party packages. Testing
this and giving some appropriate advice is the maintask of the latexbug package.
Frank Mittelbach and The LATEX Project TeamThe database inside latexbug, if you want tocall it that, is simply a comma separated key value
list consisting of file names = maintainer info. Mostof the time the maintainer info is us (meaning wemaintain it, so the file is fine) or us* (meaning it is anexpl3 package we maintain, so fine too, but should
be reported in a different issue tracker) or ignore(meaning we do not maintain it, but it is a file thatis likely to appear for one or the other reason and weshould accept such a bug report nonetheless). We
allow, for example, the use of lipsum or blindtext
to help in making up a test file with a suitable amountof text. Also often useful is the package etoolbox,
thus that is also silently accepted (aka ignored).
Any other file loaded in the bug report but notlisted in the database will show up in the error listingflagged as “third-party” code that should be removed
as explained above.
For a small number of popular third-party packages we have collected the name of the external maintainer and if available to us some extra information
so that it is easier to send to the rightful addressee
if you encounter a bug in such a third-party package.
But to keep this manageable this is only done for avery small number of the 5000+ packages out there(though we might add a few more over time).
It is however not impossible that we missed
one or another file that should have been listed as“maintained by us” but isn’t and thus incorrectly
generates an error. Another potential problem area
is with the maintainer info we provide, as that might
become invalid without being noticed.
If you run into one of those problems or noticean omission of that sort, please send us a bug reportby opening an issue at the GitHub source of thepackage which is located at:https://github.com/latex3/latexbug
Please note that the fact that a particular package iswritten by one of the members of the LATEX Project
team does not automatically mean that latexbug
will classify it as a core LATEX package. Many suchpackages will show up as “third-party” with therequest to report the bug with the respective maintainer directly.
For example, fontspec, written by Will Robertson, has its own repository, so issues involving thatpackage should normally be reported there and notwith the LATEX kernel, and latexbug will point you
in the right direction.
5

Important links

https://www.latex-project.org
Website of the LATEX Project (official site for
LATEX and LATEX3 development).

TUGboat, Volume 39 (2018), No. 147https://www.latex-project.org/bugs
Page describing how to submit a bug reportfor core LATEX. This should always contain thecorrect up-to-date links, etc.
https://www.latex-project.org/latex3/ ←code/#discussing-it
Page describing how to join the LATEX Project
discussion list and how to retrieve old posts.
https://www.latex-project.org/cgi-bin/ ←ltxbugs2html
Place to look for bugs reported prior to 2018.
https://github.com/latex3/latex2e/issues
Place to search through bug reports from 2018
onwards and to open a new bug report (“NewIssue”) for core LATEX 2ε .
https://github.com/latex3/latex3/issues
Place to open a bug report for issues involving
LATEX3 or expl3 packages.
https://github.com/latex3/latexbug
Home repository for the sources of the latexbug
package. Also contains the ready-to-use package
in case it is not in your distribution.
https://ctan.org/pkg/latex-base
The LATEX kernel sources on CTAN.
https://ctan.org/pkg/required
CTAN home of LATEX core packages that arerequired to be present in any distribution.
 Frank Mittelbach
Mainz, Germany
frank.mittelbach (at)latex-project (dot) org
https://www.latex-project.org
 The LATEX Project Teamlatex-team (at) latex-project(dot) org
https://www.latex-project.org

New rules for reporting bugs in the LATEX core software(as maintained by the LATEX Project)