Contributing to BootLoops

Contributions to BootLoops are welcome from anyone. These are the rules for the toolkit repository bootloops under the GitHub organization BootLoops-ai. The five sibling repositories there (jackandjill, amflow-cpp, kira, blade, skills) follow the same rules; each carries a short CONTRIBUTING.md stating what differs in that repository, such as its license and where changes to the original Kira, Blade or AMFlow.cpp code should go. Bug reports, work to share and requests for BootLoops to build or port a tool are covered on the Contribute & contact page.

Two ways to contribute

A tool can be added to BootLoops or linked from BootLoops. Every proposal says which in its first line.

What an addition needs

A tool of any size qualifies if it has these four things. For layout, copy tools/rankscreen/: a small package with a GUIDE.md, an optional README.md, a selftest.py entry and a battery that carries a known-answer control and planted defects.

1. A use inside BootLoops, shown by an example. The tool is called by a stage of the loop-integral or exact-arithmetic pipeline, or it produced or checked a number in a published result. The package ships a worked example that reproduces that use: the stage's real input, or the published number with a pointer to where it appears, with the command that runs it and the expected output, committed under tools/<package>/examples/ or inside the self-test so the battery can compare fresh output against it. A description of what the tool could do is not an example.

2. Documentation in the house form. Each package carries a GUIDE.md with the labeled sections the existing guides use, written as ## headings: KIND, PURPOSE, USE-WHEN, NOT-FOR, INVOKE, INPUTS, OUTPUTS, GATES (acceptance checks and exit codes), FOOTGUNS (known hazards), CREDIT and a license line. GATES lists every condition under which the output would be wrong or meaningless, and names at least one check of the output on good input against a reference value obtained independently: a hand calculation, a published value or a second method. A longer README.md is optional. Write for a reader outside your project: no internal process names; American spelling; no claim about what the code checks that the self-test does not demonstrate.

3. A self-test that can fail. The self-test (the package's test battery) compares the worked example's output with the committed expected output, runs the known-answer check named in GATES and runs one planted-defect fixture for every condition GATES lists. A fixture is an input built to be wrong in a known way, which the tool must refuse with the documented exit code. Fixtures are committed to the repository as data files or as a builder kept separate from the code under test; the checker never generates its own test input. Register the battery with one entry in tools/BATTERIES.json, keyed by the package directory name and placed in alphabetical order. Every entry has two fields: "cmd", the exact shell command, and "cwd", either "root" or "package", the directory the command runs from. The optional "serial": true puts the battery on the runner's Julia lock so it never runs at the same time as the Julia-based batteries; set it if your command launches Julia indirectly. Add the package's row, also in alphabetical order, to the index table in tools/README.md. Its last column is the verification class: selftest for a new contribution, or partial when a test needs an external program (smoke and data-gated are not available to new contributions). python3 run_selftests.py <package> then runs exactly that entry and must report PASS. The default battery finishes in about 20 seconds on a laptop and writes nothing outside its package or a temporary directory.

4. Declared dependencies and license. Standard-library Python where possible; anything else is named in the guide and installable from PyPI or listed in INSTALL.md, which also describes the supported Python setup. A test that needs an external program skips with a message naming that program. Each new source file opens with a copyright line naming you and SPDX-License-Identifier: MIT. Code derived from someone else's program says so in the file header and the CREDIT paragraph, naming the original authors and license; it is accepted only if that license permits it, and it gets a row in THIRD_PARTY.md.

A public repository; an open-source license approved by the Open Source Initiative, stated in that repository; a README that says what the tool does and how to run it; one runnable example with its expected output; and your name as it should appear in the listing. The house guide form and a registered battery are not required. A link needs no pull request: when the maintainers accept one, they write the listing in the toolkit index on this site and the matching entry in the repository's catalog of external tools.

The index lists tools a BootLoops user would reach for: multi-loop Feynman integrals, exact and finite-field arithmetic, integer-relation fitting, differential equations and the application areas that have pages on this site. Links outside that scope are declined, with the reason given on the issue.

Proposing and submitting

For a new tool, added or linked, open an issue before any pull request, using the Tool proposal form on the bootloops repository. It asks whether you want to add or link, which pipeline stage or published result the tool serves and for the worked example; for an addition it also asks for the state of the guide, the battery and the dependencies. A maintainer answers on the issue whether the proposal fits as an addition, as a link or not at all, and why. There is no fixed response time; tools@bootloops.ai reaches the maintainers if an issue sits unanswered, and a declined proposal can be revised and reopened on the same issue. For an addition, fork the repository, branch from main and open the pull request against main, referencing the issue; the pull-request template repeats the four requirements as checkboxes.

A bug fix goes straight to a pull request with a test that shows the bug; if the bug cannot be captured in a test, describe how to reproduce it in the pull-request body. Documentation fixes also go straight to a pull request. Every pull request, of any kind, states in one sentence that the contribution is your own work, offered under the repository's licenses. Bug reports without a fix, page corrections and suggestions go on the forms at github.com/BootLoops-ai/feedback, as the Contribute page describes.

What review checks

For an addition, a maintainer makes a fresh clone of your branch and runs python3 run_selftests.py --par 8; every package must come back PASS, yours included. Packages of class data-gated refuse without their data and print REFUSED (by design), which is expected (INSTALL.md, "Verifying an installation"). Each exit code in your guide is exercised and must behave as written. Every claim that the tool rejects bad input is tested with a deliberately bad input your battery does not already contain; a silent pass on malformed input comes back as a required change, and conditions missing from GATES are added to it. The guide is read for plain wording a reader outside your project can follow, and for claims the code does not back. The alphabetical order of tools/BATTERIES.json and of the index table is checked. For a link, a maintainer reads the README, runs the example and checks the license. A round of requested changes is normal, not a rejection. Updating the package counts in README.md and tools/README.md, placing the tool in the grouped tool list (toolkit/ours/README.md) and writing its tool page on this site are maintainer tasks done at merge.

Credit and license

BootLoops code is released under the MIT License, copyright (c) 2026 Anthropic, PBC; its documentation and figures under CC BY 4.0; third-party components keep their own licenses, listed in THIRD_PARTY.md. An added contribution joins the repository on those terms, with your copyright line kept in your files. You are credited as the author in the commit history, in the package's CREDIT paragraph and, for substantive work, in the record of contributions. A linked tool keeps its own license and is listed with your name beside the link.

Questions

Ask on the feedback repository or write to tools@bootloops.ai.