Growing Mathlib: maintenance of a large scale mathematical library

TL;DR

This paper discusses strategies for managing the rapid growth of the Lean Mathlib library, focusing on change management, quality control, and tooling to ensure sustainable development.

Contribution

It introduces specific methods such as deprecation systems, linters, and custom tooling to handle growth, quality, and technical debt in a large formal mathematics library.

Findings

Effective deprecation reduces breaking changes.

Code quality tools improve user feedback.

Design choices speed up compilation.

Abstract

The Lean mathematical library Mathlib is one of the fastest-growing libraries of formalised mathematics. We describe various strategies to manage this growth, while allowing for change and avoiding maintainer overload. This includes dealing with breaking changes via a deprecation system, using code quality analysis tools (linters) to provide direct user feedback about common pitfalls, speeding up compilation times through conscious library (re-)design, dealing with technical debt as well as writing custom tooling to help with the review and triage of new contributions.

Full text

1 Introduction

The mathematical library Mathlib [36], written in the Lean theorem prover, is perhaps the fastest-growing library of formalised mathematics. Created in 2017, it now contains 1.9 million lines of code across a broad range of subjects. Mathlib’s focus on being an integrated library for mathematics makes it well-suited for formalising current research mathematics. Recent formalised results based on Mathlib include a fundamental result of Scholze and Clausen about condensed mathematics [33, 7, 6], Smale’s sphere eversion via an $h$-principle [9], Campos–Griffiths–Morris–Sahasrabudhe’s breakthrough on upper bounds for diagonal Ramsey numbers [28] and Gowers–Green–Manners–Tao’s breakthrough on Marton’s polynomial Freiman–Rusza conjecture \citesPFR1,PFR2,PFRImproved. Mathlib is also crucial for Buzzard’s ongoing project [5] to formalise a proof of Fermat’s Last Theorem. In a different direction, Mathlib has been used in industry research, such as for verifying the correctness of the SampCert differential privacy framework [26].

Mathlib is run by a community of users as an open source project, enabling and encouraging contributions by users with a wide range of backgrounds and expertise. This allows for a broad range of contributions (of formalisations, but also with the infrastructure and other supporting work). At the same time, this presents challenges around knowledge transfer and ensuring the library stays coherent as a whole. To address this, Mathlib makes extensive user of linters, to help users with intricacies of the Lean proof assistant and enforce certain global coherence properties. (We describe this in Section 4.)

Mathlib’s continued growth also presents other challenges for scaling. Some of these are technical—such as adapting existing code to other changes in the library (Section 3), ensuring that Mathlib continues to compile reasonably quickly (see Section 5) and managing technical debt (see Section 6). With any large group, social processes become pertinent (such as, ensuring all communication stays friendly and welcoming (Mathlib has a code of conduct with a dedicated team enforcing it), or keeping some alignment on an overall vision of Mathlib). A key process in both maintaining a coherent library and teaching new contributors about formalisation best practices is mandatory code review. This process needs to be supported and adapted to scale to the influx of contributions (see Section 7).

We describe the Mathlib community’s strategies for dealing with this growth, focusing on the above aspects in turn. The use of linters (in a less extensive way) was already described in previous work [37]; the other sections are new. While some details are specific to Lean and Mathlib, we believe that many of them apply broadly to libraries of formal mathematics knowledge.

2 Related work

Various interactive theorem provers have come to enjoy large libraries of research mathematics—each with its own strengths and weaknesses. The Mizar Mathematical Library [2] is the oldest and perhaps the largest library (at 3.7 millions lines of code (MLOC)) of formalised mathematics. The Isabelle/HOL system has very powerful automation; the Archive of Formal Proofs (AFP; 4.8 MLOC111The AFP has a broader focus [3], with about half its current articles covering the analysis and verification of particular algorithms. Arguably, this makes the MML a larger library of formalised mathematics.) still has the strongest complex analysis library. The Rocq theorem prover allows expressing complex mathematical objects (such as schemes, the tangent space of a manifold or vector bundles) more naturally, thanks to its foundations including dependent types. While its mathematical components library [23] is significantly smaller (150 000 lines of code), Rocq has been used to formalise major results such as the Four Colour and the Feit–Thompson theorems (which are each of similar size as the mathematical components). Let us also mention the Flyspeck project [15] as an example of combining large libraries in two different proof assistants.

The MML introduced mandatory review of contributions in 2006, as well as tooling to check for duplicate lemmas. (Such tooling also exists for Rocq [10] and Lean [31].) Klein et al have written [4] about maintaining large-scale Isabelle libraries. They name many challenges similar to ours, including coordination and collaboration in large and diverse projects. The Isabelle system also employs custom linters [27] — which are not mandated for existing entries, but enforced for new submissions. Zimmermann [39] has written about recent changes to Rocq’s development processes (including switching to GitHub and a pull-request based model, dealing with breaking changes and the challenges with distributing reviews). There is also custom tooling to support Rocq maintainers [40]. Huch’s in-progress PhD thesis [17] describes efforts to address scaling issues in the AFP, including a discussion of maintainenance efforts.

Growing a large formal library can require changes to the underlying prover. Such work on Lean is out of scope of this paper; Wenzel discussed it for Isabelle [38]. They also describe tooling to automatically test the impact of core system or theory changes on dependent projects.222Similar tooling for Lean does not exist yet, but is being planned by the Lean FRO. Test-case minimisation [14] can also be instrumental for quickly diagnosing and fixing broken proofs “downstream”. Huch and Wenzel have also written about the challenges of maintaining and scaling Isabelle’s supporting infrastructure [18, 19].

There is also considerable work on proof repair, such as adjusting code to breaking changes. Luan et al [22] have studied and classified compatibility issues in the AFP. Tan et al [35] have developed tooling for automatically fixing proofs in Isabelle/HOL. Gopinathan et al [11] have developed proof repair tooling for the Rocq prover.

Despite the growth of large libraries of formal proofs, there is still relatively little work describing tools and best practices for their maintenance. Ringer et al [32] note the gap between proof engineering and software engineering in this respect.

3 The deprecation system

Maintaining Mathlib involves changing existing code. Generalizations, refactors, reorganization of content, syntax changes and so on are exceedingly common in Mathlib. As a result, code written for one version of Mathlib may no longer compile with a newer version. This applies both within Mathlib (contributions to one area need to deal with effects on all other areas), to contributions under review and particularly to projects depending on Mathlib. Many large formalisation projects are carried out in a repository depending on Mathlib. If keeping up with the latest Mathlib changes is too onerous, contributing results back to Mathlib may become impossible.

The spectrum of possible breaking changes is rather diverse, and ranges from one-off changes when upgrading to the next Lean version to adjusting to particular refactorings in Mathlib. In principle, Lean’s excellent meta-programming facilities allow writing custom migrations for virtually all changes, transforming working code from one version to the next. Theoretically, such migrations could be arbitrarily complicated. In practice, however, the vast majority of adjustments are very simple to deal with: renaming (the declaration which states) a theorem or definition, renaming files (which requires adjusting sec:linters); these can also help with semantic changes.

Lean has a deprecation system specifically designed to handle renamings gracefully. When a declaration is renamed, for a grace period of several months, we add a deprecation marker documenting the rename. This connects the old and new names (and allows providing a custom message to guide the migration process). Upon using a deprecated declaration, the user sees a warning, indicating which declaration to use instead. This allows for a much smoother migration.

Dealing with renamed files is harder. Lean looks at file imports before the deprecation system (which is implemented as a linter) has the chance to run—so a file that imported the file with the old name would stop building entirely. The solution is similar: the module with the old name is not erased, but is preserved and stained. Thus, it can be imported without breaking the build—and a linter suggests to replace the old module name, with appropriate imports. These could be either the direct imports of that module, in the case of a reorganization of content; or the renamed module, in the case of a simple move. This informs users of where the declarations that were present in the old file may have ended up.

4 Semantic linters

In general terms, a linter is a program whose purpose is to ensure that the code in a project satisfies certain requirements. The term requirements should be interpreted very broadly: a linter could enforce

• •

code style conventions (such as the default indentation of code);

• •

file naming conventions (such as never using paths that differ only in capitalization);

• •

function naming conventions (such as making sure that namespaces in declarations are not repeated);

• •

deprecating commands that have been replaced by newer code;

and in fact Mathlib uses linters for all of these purposes.

To be precise, Mathlib uses two different linter frameworks, with distinct strengths and weaknesses. Lean itself provides a https://lean-lang.org/doc/reference/latest//Notations-and-Macros/Defining-New-Syntaxsyntax of the command as input and can run arbitrary code.333Technically, a linter function returns a , i.e. the only interesting outcomes of the linter are its side effects.Lean’s community-maintained extended library Batteries provides the parallel structure

command and has access to the syntax tree of each command, while the latter is designed to run once on the “final” environment and only inspects the declarations present in the Environment. We refer to the former linters as “syntax linters” and to the latter linters as “environment linters”. Both are semantic linters, in the sense that they can access the fully elaborated information and not merely the typed syntax. Since both frameworks allow running arbitrary code, the distinction between them is mostly on what they are expected to do and what they can do easily, not on what they could do. Environment linters are good for global validation (e.g. checking lemmas are in normal form), but only warn you after the fact. Syntax linters warn you right away and are best suited for local validation (e.g. the valid notation $\lambda$ x => x is deprecated in favour of fun x $\mapsto$ x).

At the time of writing, there are 26 syntax linters defined in Mathlib and 10 more coming from its dependencies, as well as 17 environment linters, all but two defined in Batteries. We mostly focus on the syntax linters: virtually all the environment linters have been described previously [37].444With the advent of Lean 4, the need for the typeclass linters described there has mostly disappeared: typeclass inference was substantially redesigned in Lean 4 [34], taking into account the insights from Mathlib development. This means some linter warnings have become compiler errors, and the others have become less relevant and did not get reimplemented in Lean 4. To summarize more coherently how Mathlib uses linters, let us group them into general categories and highlight a few examples from each category.

4.0.1 Deprecation linters

As mentioned in the previous section, linters help dealing with deprecations. Breaking changes could arise from certain tactics becoming more powerful or more efficient, making other tactics obsolete or undesirable. In such situations, the replaced tactics would be deprecated. The syntax linters, as opposed to the environment linters really shine: simply inspecting the environment, it is virtually impossible to recover which tactic produced which proof term. However, the syntax of the declaration clearly contains this information very prominently.

4.0.2 Style linters

Mathlib has a fairly detailed style guide (which helps to settle discussions about individual formatting preferences efficiently). Mathlib’s style linters enforce various aspects of coding style and formatting, such as line length, whitespace conventions or the formatting of documentation comments. This allows reviewers to focus their time on higher-level aspects, and helps contributors learn about Mathlib style without having to read all style rules at once. We also enforce that every Mathlib file (that is not an Import structure linters Keeping track of Mathlib’s import structure is important for organisation and compilation speed. A Lean module can only be compiled once all its dependencies have been fully checked555Lean’s upcoming module system will change this trade-off, if and when it is adopted in mathlib. (Doing so is desirable in principle, but requires a lot of conscious library design work.): thus, a reasonable import structure enables parallelism and faster overall compilation. It also speeds up local development, as changing multiple files requires less recompilation, and makes it easier to place a new mathematical result. Mathlib has two main tools to help with keeping the import structure organised: Mario Carneiro’s shake tool warns about unused imports, and the

4.1 Style linters

Style linters primarily inspect the syntax tree of each command. A slightly imprecise but descriptive way of thinking about them is that they match syntax-aware regular expressions.

An example in this category is the docstring linter. This performs a simple check on doc-strings, making sure that they begin with exactly one space or line break before the first non-whitespace character, and they perform a similar check for the closing of doc-strings.

Uniformizing the appearance of doc-strings contributes to a homogeneous file layout which is helpful when scanning the source code by eye.

Another style linter is the itemize

contains a valid copyright header,

does not import files like Mathlib.lean or Mathlib/Tactic.lean,

contains a module doc-string, summarising the content of the file (unless the file is an itemize This ensures a common format for all the Mathlib files and also takes a step in the direction of minimizing the dependency structure of Mathlib. There are other, specific tools that are geared specifically towards controlling imports, such as DirectoryDependency, but this is a quick and simple syntactic check.

4.1.1 Code pruning

Another class of linters highlights redundant code. For instance, the unusedSeqFocus, the unreachableTactic linters, each highlighting different ways in which a tactic proof can be simplified or streamlined.

4.1.2 Tracking issues

Certain commands are expected to be rarely used, or are only temporary adaptations. For instance, increasing the time limit for type-checking is something that may be necessary for an individual declaration, but increasing the limit for a whole file is likely a symptom of some deeper issue that should be addressed. Hence, a command such as setOption linter does exactly that: it flags uses of set_option maxHeartbeats x in … instead.

Similar linters exist for globalAttributeIn linter that warns that the scope of certain attributes is not “local”, even in the presence of the (usually) scope-limiting Maintenance and code readability

The linters in this category are specifically geared to improve maintainability of code and readability. Since Mathlib evolves very quickly, code breakage is fairly common; any tooling which can diagnose and prevent such breakages is immensely helpful. The linters in this section try to be pro-active about code breakage by reducing code brittleness.

Rigid and flexible tactics

The simp, aesop) apply to a wide variety of goals and return similarly varied processed goals; “rigid” tactics (such as apply) perform some very specific operations and may stop working even with very small changes of the current goal state.

The simp lemma allows further simplification, making the following ring or Handling multiple side-goals In terms of goal management and readability, the ·. The code style enforced by this linter makes both the number of side-goals that remain after each tactic application as well as which parts of the code deal with which part of the proof completely transparent. This helps with maintenance, since it limits code breakage to easily identified branches, rather than a generic total failure. At the same time, it also improves code readability and structure, since the various arms of the proofs are visually differentiated.

Closing sections

Finally, let us mention the section commands that do not have a matching section, producing a dangling one. As a consequence, the scope of the currently non-Helpful and pedagogical suggestions

Some linters attempt to preempt possible misunderstanding or common pitfalls. The have when introducing a non-let when introducing an assumption in have for papercut linter. One common mistake is accidentally using subtraction of natural numbers (which truncates at

4.1.3 Prototypes

• •

MetaTest

• •

Relative

5 Speeding up Mathlib

As Mathlib grows to encompass more declarations, the time to build it will also increase. Keeping build times manageable requires constant attention to sources of slowdowns and inefficiencies. The Mathlib Speedcenter is an instance of the benchmarking server VelCom that builds and benchmarks all commits to the master branch of Mathlib. The benchmarks include overall measurements for Lean components such as the simplifier or typeclass inference, and per-file compilation timings. In addition to wall-clock (overall time from start to finish) and task-clock (takes into account parallelism) times measured in seconds, most benchmark results are measured in instructions, since the number of instructions is more stable on the benchmarking servers than the wall-clock time which is affected by process scheduling. Continuous monitoring of build times is crucial to ensure no unexpected slowdowns occur. Therefore, a bot reports notable outliers in benchmarks (changes of a measurement by 5% or more) on the Lean community Zulip chat.

5.1 Speed and typeclasses

Mathlib relies on the Lean typeclass system to perform automatic inference of many implicit arguments. Typeclasses are flexible and have low infrastructure requirements on user code, but the flexibility also means designs have to be carefully consider to optimize their tradeoffs. As the typeclass hierarchy grows, synthesis of instances becomes slower since a larger search space needs to be explored. It is not only important to ensure synthesis succeeds quickly: if synthesis fails, tactics can decide to fall back on an alternative proof strategy. Lean’s instance synthesis algorithm fails only after exploring the full search space, and it is therefore especially important that the space does not grow too large.

One fundamental consideration in Mathlib’s typeclass design is the level of bundling \citesBaanenUseAndAbuse, Mathlib, which concerns the way conjunctions of assumptions are modeled in classes. For example, to represent ordered commutative monoids, we can define a bundled class CommMonoid, CommMonoid with the (existing) order class IsOrderedMonoid class. Unbundling makes parameters more verbose: [CommMonoid M] [LinearOrder M] [IsOrderedMonoid M]. As described with more detail in [1], bundled design is preferred for its conciseness in Mathlib when possible.

The speed tradeoffs changed when upgrading from Lean 3 to Lean 4. A consequence of the bundled approach to typeclass design is that the number of classes becomes multiplicative when extending along two distinct axes. Taking the LinearOrderedCommMonoid, or in the algebraic hierarchy to give LinearOrderedCommGroup. When looking for a [CommMonoid M] parameter with [PartialOrder M] with https://github.com/leanprover-community/mathlib4/pull/20676refactor by Yuyang Zhao resulted in a 20% decrease in typeclass inference time, resulting in a 6% overall speedup to Mathlib compilation.

5.2 Speed and coercions

The coercion system is another commonly used component of Lean. Essentially, when a term A, where type t. The coercion is found by synthesizing an instance of the typeclass CoeT should not be declared directly, but rather chained together from the CoeOut, CoeTail typeclasses. The rules for which typeclass to instantiate for a particular coercion are subtle and not universally understood; they are notably more complex compared to Lean 3. As a consequence, a seemingly acceptable instance can cause a large performance regression. For example, B to be a free variable, but doing so causes large performance regressions since such an instance always applies.666https://github.com/leanprover-community/mathlib4/pull/22950

In a similar vein to Subsection 5.1, large hierarchies extending coercion typeclasses should be avoided. Mathlib uses the MonoidHomClass used to extend the FunLike hierarchy. Even worse, since Monoid instances, this also triggers a search through the algebraic hierarchy. The solution was to unbundle inheritance from FunLike and https://github.com/leanprover-community/mathlib4/pull/8386refactor by Anne Baanen performing this unbundling resulted in a 33% speedup for typeclass instance synthesis and an overall 19% decrease in build instructions.

5.3 Speed and definitional equality

Type checking, and definitional equality in particular, is commonly invoked in the Lean elaboration and kernel checking process and can result in arbitrarily complex computations: terms can be large and their size can increase further when unfolding definitions referenced by the term. Equality checks are intended to be “cheap” basic steps in implementing more complex routines such as typeclass instance synthesis, so slowdowns in checking have a large impact.

Generally, definitions are designed to not require unfolding unless the unfolding is requested. Each definition in Lean has a transparency level controlling the circumstances in which it is unfolded. Most tactics are designed to only unfold definitions explicitly marked as reducible, with some tactics also unfolding at the default semireducible transparency level. Marking definitions as irreducible prevents unfolding altogether, skipping a potentially expensive equality check if it does not obviously succeed.

A particular example of complex definitional equality checking can be found in structure declarations. Large structures can already be quite complex terms in themselves, which can be hidden behind further definitions and constructions, and the possibility of diamond inheritance can then result in nonobvious equality checks. This all results in high levels of unfolding being required to verify the equality of terms.

Typeclasses in Lean are implemented as structures, so the complex typeclass hierarchy also has an impact here. The fast_instance term elaboration macro that normalizes instance declarations by unfolding definitions and replacing subterms with synthesized instances. An initial implementation of this macro resulted in a 5% decrease in type checking time and halved compilation times for many files.777https://github.com/leanprover-community/mathlib4/pull/20993

5.4 Speed and tactics

During the compilation of Mathlib, Lean spends approximately 14% of its time running the discrimination trees [25, 30] that allow for efficient association of terms with values. A discrimination tree is a tree datastructure whose branches are indexed by symbols (either a constant, or the special symbol *. Still, the approximation is much finer than previously in Lean 3, where terms were indexed by only the first constant that appeared [29].

The simplifier tries to repeatedly rewrite using a set of lemmas and tactics (called a simp from the default large simp only keywords) since many fewer lemmas have to be tested for applicability. Going from simp lowers the maintenance burden, since a change to the default simp only call.

The div_self a : a / a = 1 applies if Group, but a field does not form a multiplicative group. Therefore, the https://github.com/leanprover-community/mathlib4/pull/21326

Another avenue to optimizing the use of tactics is to use weaker, faster tactics instead of more powerful but slower tactics. The Aesop tactic provides general proof search [21] and is also invoked as part of other, more specialized tactics to discharge goals. The general nature of this proof search makes Aesop very powerful, but this power is often unnecessary when the proof it needs to find has a predetermined format. We have found that replacing powerful Aesop-based tactics like fun_prop is almost always possible and reduces running time appreciably. Similarly, small tweaks such as applying local hypotheses or trying reflexivity to discharge an equality goal before starting Aesop can lead to appreciable speedups.888https://github.com/leanprover-community/mathlib4/pull/21330

6 Tracking and addressing technical debt

Ward Cunningham introduced [8] the term technical debt in 1992, writing:

Shipping first time code is like going into debt. A little debt speeds development so long as it is paid back promptly with a rewrite. Objects make the cost of this transaction tolerable. The danger occurs when the debt is not repaid. Every minute spent on not-quite-right code counts as interest on that debt. Entire engineering organizations can be brought to a stand-still under the debt load of an unconsolidated implementation

This concept is all the more important in a large foundational library like Mathlib, especially in light of its cohesive and tightly integrated nature. In this section we describe various types of technical debt we have encountered in Mathlib, and how the community tracks and addresses them.

Porting notes

From 2021–2023, the community ported Mathlib from Lean 3 to Lean 4. This process ought to be documented in more detail elsewhere, but for the purposes of the present discussion we summarize the points of interest.

For all practical purposes, Lean 4 is a distinct language from Lean 3—there is no backwards compatibility. Mario Carneiro wrote a tool mathport that automatically translates Lean 3 code to Lean 4 code on a best-effort basis, and a small group of people implemented the common tactics in Lean 4. In October/November 2022, this preparatory work transitioned into a wide-scale and coordinated effort to port the theory files of Mathlib. Over the course of 10 months, the community ported on the order of a million lines of code, or roughly a dozen files per day.

Naturally, there were many places where a faithful translation was not possible. For the sake of speed, the porting team decided to liberally annotate issues with “porting notes” that described the problem and the workaround. As a result, by the summer of 2023, the porting process was complete, but Mathlib 4 contained well over 5000 porting notes.

Pietro Monticone made a valiant effort to organize and classify the porting notes in February and March of 2024. Subsequently, Anne Baanen, Kim Morrison, and Johan Commelin processed and addressed over two thirds of the porting notes in the first quarter of 2025. Many of these porting notes became obsolete because of new and expanded functionality in Lean 4. At the time of writing, roughly 1500 porting notes remain.

Adaptation notes and backwards compatibility flags

New versions of Lean 4 are released on a monthly basis. Mathlib maintains a branch that tracks the nightly releases, which simplifies migrating to the new version of Lean 4 when it is released. This tracking branch provides feedback for the development of Lean 4: if the daily transition to a new nightly version of Lean 4 requires some unsatisfactory workarounds, then these are annotated with #adaptation_note comments. In essence, these notes have the same functionality as porting notes. Occasionnally, there is no simple solution for a problem that arises from a new version of Lean 4. In such an event the old feature can be re-enabled via a backwards compatibility flag. This allows the Mathlib community to transition to the new version of Lean 4 at a reasonable pace.

Reporting technical debt

The shell script scripts/technical-debt-metrics.sh is used to create a report of the current state of known technical debt in Mathlib. This includes tracking adaptation notes, porting notes and backwards compatibility flags. Continuous integration runs this script on a weekly basis, and posts the report (including the delta with respect to the previous week) to the Zulip chat of the Lean community. Additionally, this report is computed for each pull request, and posted to a dedicated “PR summary” comment at the top of the pull request. This allows the reviewer to quickly see the current state of technical debt in the pull request, and take this into account when deciding whether to approve the pull request.

Mathlib also has a mechanism in place to surface pull requests addressing technical debt: this includes both a dedicated label and triage dashboard (see Section 7.2) and a Zulip stream where such PRs can be brought to attention.

One downside of tracking and reporting technical debt in this manner is indicated by Goodhart’s Law: “When a measure becomes a target, it ceases to be a good measure.” In this context, this means that the community is inclined to focus on the technical debt that is being tracked, whereas there may be other forms of technical debt that fly under the radar. To alleviate this, there is a dedicated thread on the Lean community’s Zulip chat listing less measurable forms of technical and organisational debt. (One example of the latter is documenting unwritten informal Mathlib policy: sharing such knowledge enables other contributors to learn this for themselves and lowers the barrier towards contribution. An example of the former is reorganizing top-level directories: due to Mathlib’s age, some of these are not coherent any more.) Everybody can add items to the list, facilitating a collective understanding of future maintenance tasks.

7 Scaling code review

Since its beginning, the Mathlib library required code review prior to merging changes. This is enforced through the bors bot: pull requests are merged automatically upon approval by an authorised user (i.e., a Mathlib maintainer).999Using bors also enforces the not rocket science principle [16]: ensuring that the main (development) branch of Mathlib always passes all continuous integration tests.

This policy has several reasons. For one, formalisation in Lean ensures a strong level of correctness: a formalised mathematical proof which compiles without any and is not intentionally manipulating the Lean environment or adding additional axioms—both of which are checked for by Mathlib’s continuous integration will be a correct and complete proof. However, designing an integrated mathematical library well still requires expert knowledge: usually, there are different potential designs, with vastly different usability and ergonomics. Code review is one way to form and share common knowledge about design best practices. It also has an empowering function: new contributors can propose new code, without being afraid of breaking other proofs (if their code compiles, the proofs are still fine) or overlooking important aspects—because an experienced Lean user will look over their contribution. This way, code review is a way of teaching and onboarding new contributors.

Mathlib is growing steadily, as is its influx of new contributions. At the same time, many of its contributors are volunteers or work on Mathlib as a side project. Most of Mathlib’s maintainers have teaching, administrative or supervision commitments: allowing Mathlib to scale requires lightening their work. This has both social and technical aspects. On the social side, maintaining Mathlib means embracing teamwork and delegating responsibility. Approval of Mathlib pull requests is a multi-stage system, allowing many people to contribute.

Code review in Mathlib is decentralised: everybody is allowed and encouraged to review contributions; there are guidelines teaching what to review for. This ranges from more basic aspects (such as adherence to Mathlib’s style guidelines, or whether new documentation is comprehensible) to advanced aspects like the correct code location and library design patterns. There are regular review meetings, where reviewers and interested contributors review code together—both to make this work more enjoyable, and to mentor potential new reviewers.

Mathlib’s maintainers have the final say on approving a pull request. The number of maintainers keeps growing steadily, and is currently around 30. Maintainers have different specialisations; together, they cover the breadth of Mathlib. Having multiple knowledgeable maintainers in one area is beneficial, so they can discuss difficult decisions.

Between maintainers and all contributors is the group of Mathlib reviewers. These are Mathlib contributors who have provided useful reviews in the past. A reviewer can approve a pull request by commenting maintainer merge, which notifies the maintainers. Usually, these get merged (or at least discussed further) more quickly. This system is a bit like journal referees and editors: the reviewer group lightens the load on maintainers; the direct notification mechanism provides an additional small incentive for reviewers. This works well in practice: in the last year, about one in three merged pull requests was approved by a reviewer before they were merged.

On a technical level, we can save reviewer and maintainer time by automating tedious or mechanical aspects of this process. Two basic means of automation are using continuous integration with bors and automatic maintainer notifications through the maintainer merge command. Let us discuss Mathlib’s review automation from two further angles: tooling for reviewers and tooling for triage.

7.1 Tooling for reviewers

There are multiple ways for automation to support pull request reviewers. To begin with, we need to find a suitable reviewer for a given pull request. A pull request with a new theorem is best reviewed by somebody familiar with the theorem’s area; something similar holds for a contribution improving Mathlib’s infrastructure, adding a new linter or adding a new tactic. Each new pull request adding new content is automatically labelled according to its area. There is a file collecting each reviewer’s area of interest and expertise. This allows automatically suggesting suitable reviewers for every pull request—taking their expertise and reviewing capacity into account. At the time of writing, this automatic assignment is run on an experimental basis. This labelling information has also been used to identify missing reviewers: if pull requests in a certain area take a long time to get reviewed, recruiting further reviewers could be worthwhile.

Secondly, we have created custom tooling exposing important information to reviewers. When a pull request is filed, a script creates a sticky comment summarising key information about a PR. This comment is updated in-place as the pull request is amended. The comment shows which lemmas were renamed (so reviewers can spot those more easily, and check if deprecation warnings are present). It also exposes when transitive imports of files change, which is extremely helpful for reviewing import refactoring. Finally, the summary comment shows any changes in technical debt metrics.

Further, there is substantial automation to help with information flow within the project. Collaboration on Mathlib occurs primarily on two sites: GitHub, where git repositories including Mathlib and its dependencies are hosted, and the leanprover-community Zulip, a moderated chat site where community members discuss their contributions and other Lean-related topics. Automation can help with bridging these two venues and keeping some information synchronised. Whenever a specific pull request is mentioned in the Zulip chat, a script posts an emoji reaction indicating the current pull request status (such as, whether it is waiting for author changes, a review or was already merged). This allows reviewers and maintainers to see at a glance if action has already been taken. This reaction is updated by a GitHub actions script whenever the pull request’s status changes.

We make extensive use of Zulip’s custom linkifier feature to allow users to link directly to issues or pull requests in the Mathlib repository, Mathlib documentation entries, and other useful pages.

7.2 Triage tooling

The number of open Mathlib pull requests is growing steadily. At the time of writing, there are about 1500 open pull requests. Often, new pull requests are getting reviewed quickly, but their sheer volume makes it difficult to keep track of every single PR. Better tooling helps to ensure that every pull request is kept track of and receives a timely response.

Investigating this closely shows that different users of such tooling have differing needs. For instance, a reviewer may want to find reviewable pull requests matching their areas of interest. Mathlib’s maintainers would like to know about pull requests which were already approved by a reviewer. Other contributors may be interested in recent pull requests to “see what is going on”, or viewing all pull requests related to a particular area. Pull request authors may want to see the status of all their pull requests or find out why their pull request is not on the review queue. Most importantly, a triage team (see below) keeping track of pull requests’ state needs better tooling to see the state of each pull request.

GitHub’s default interface can do many of the above tasks; however, at Mathlib’s scale we have increasingly run into its limitations. For example, to triage reviewable pull requests one would like to know the total time a pull request is already waiting for review. This need not be a continuous time span, so computing this needs to consider a pull request’s change over time. GitHub only exposes a “last updated” date, which does not provide this. (In addition, this “last update” measures almost every activity, which is often too sensitive for our purposes: a bystander’s comment or a notification of a merge conflict resets the last activity counter, but need not mean review activity.) Similarly, sorting pull requests by their total diff can be useful information, as is the number of PRs depending on a given PR.

We have built a custom editorial tool to address all these shortcomings. Pull requests are grouped by their status (such as waiting for review, blocked on another pull request or waiting for the author to respond to review comments). These categories are tailored to Mathlib’s infrastructure (for instance, pull request failures related to Mathlib’s infrastructure are highlighted automatically, speeding up the diagnosis and fix). In each category, we compactly display (see Figure 1) all pull requests together with additional meta-information such as its author, title and labels, but also additional information such as diff size or the total time in review. These lists can be semantically sorted by each category. This tooling can adapt and grow with Mathlib’s needs easily.

We ran a survey among Mathlib contributors, reviewers and maintainers. The results provided many useful suggestions for improving this tool further (many of which have already been implemented). The survey result also affirms that this changes how contributors look for pull requests: the dashboard has become part of many maintainers’ standard workflow. The triage functionality in particular is used by maintainers, but also by the newly-founded triage team: having a common webpage to look at makes this process a lot smoother.

Under the hood, this dashboard has two components. One keeps a cache, containing the metadata we care about for every open pull request. Periodically, we query GitHub’s graphql API to update this data for any pull requests which received updates, in effect creating a database of each pull request’s relevant state. The code for this amounts to a few hundred lines of shell and Python scripts: this could easily be run on a local computer, coupled with a cronjob.

The other component is responsible for the final user interface. It processes the downloaded metadata to extract the aggregate data we care about. (For instance, from the history of all label changes on a pull request, we determine the total time that PR was ready for review.) Using this metadata, we create the triage dashboard. The dashboard is a static webpage, using jQuery datatables to create the dashboards in each category: these can be sorted and filtered dynamically. Using a static webpage means fast response times (filtering a list of pull requests is almost instantaneous), but means the webpage needs to be manually refreshed to see updated changes. Altogether, this project consists of about 4500 lines of Python code, and about 1000 lines of shell scripts, .graphql schemas etc.

8 Conclusion

Growing Mathlib would be impossible without automation to scale its maintainance: this applies on the social, organisational and technical levels. While we cannot measure its effects precisely, the fact that Mathlib still grows fast shows how useful it is. For instance, Mathlib’s deprecation system has made updating to a newer version of Mathlib a much smoother process. Currently, such updates still require manual work, but this task can be automated well: both for deprecated declarations and modules, there are prototype tools performing the replacement automatically.

An auto-formatter for Lean would improve dealing with code style questions significantly. Lean’s extensibility makes this difficult in general: users can define new syntax and custom notation, which can drastically change the look and feel of the language.101010For example, one can allow users to write in a form of controlled natural language [24]: formatting that would be a very different endavour. Formatting user-defined syntax and notation requires knowing the preferred formatting for these. While Mathlib makes extensive use of custom notation to make its code resemble mathematical notation, this is relatively benign: all syntax has an associated pretty-printer which indicates some reasonable formatting.

Mathlib’s review and triage dashboard is mostly Mathlib-agnostic: the particular PR categories are tuned to Mathlib, but the underlying logic is not. With appropriate configuration, other open source projects could use this as well.

Acknowledgements

We would like to thank the anonymous referees for their helpful comments and suggestions. Michael Rothgang was funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) under Germany’s Excellence Strategy – EXC-2047/1 – 390685813. This material is based upon work supported by the U. S. National Science Foundation Award No. DMS-2302263.