Contributing

Set up your environment

The development guide explains the full setup. You need Docker with Compose v2, Git, GNU Make and Bash. On Windows, run the Make commands from Git Bash or WSL, the Windows Subsystem for Linux.

git clone https://github.com/test-intelligence/testlookup.git
cd testlookup
make dev                  # starts the core development services

Other commands you’ll use:

make quickstart           # starts the core demo instead
make dev-llm              # also starts the local AI model and downloads the model versions TestLookup uses
make stop                 # shuts everything down
make clean CONFIRM=yes    # deletes every data volume

The first run creates a local settings file with passwords and keys for your machine. It never overwrites a settings file that already exists. The clean command deletes all stored data. It runs only when you add the confirmation shown above, so use it only on a copy you can throw away.

Details: the settings file is .env.

Set up a separate development copy.

Check existing issues

Before you start, search the issue tracker and the open pull requests, so you don’t repeat work someone has already started. The issue tracker is the live list of what’s being worked on, what’s planned and what’s on hold.

Open an issue and agree on the approach before you write code if your change does any of these things:

• adds a connection to an outside service
• changes the structure of the database
• changes the on/off feature settings, called feature flags
• changes the tools TestLookup offers to AI assistants through its MCP server
• touches sign-in, permissions or the separation between projects
• adds a new dependency

To suggest a new feature, fill in the Feature request form and wait for a maintainer to reply before you write code. Issues labelled good first issue cover one area and point you to the code involved.

Report security problems privately through GitHub’s private vulnerability reporting, as the security policy describes. Please keep them out of public issues. For questions, start with the support guide.

Create a branch

Fork the repository on GitHub, then create a branch for this one change, starting from the main branch. If you’re already working on another branch, use a second clone or a Git worktree for the new one.

Two copies on one computer still share the same Docker container names, ports, networks and storage volumes. Run only one copy of TestLookup at a time, unless you’ve written and tested a complete override of the service settings.

Keep passwords and keys, the local settings file, generated secrets, local data and unrelated changes out of your branch. Commits must not contain secrets, private server names or paths from your own computer. The project’s automated checks reject anything that looks like a real API key, a private network address or a Windows user folder path.

Keep changes small

Keep each change small and explain why it’s needed. Make each commit stand on its own, with a short subject line of 72 characters at most, written as an instruction. In the commit body, explain why you made the change, any edge cases and the other options you considered.

Keep code tidy-ups separate from changes in behavior when that makes review easier. To add a new API route, report reader, AI agent or client feature, follow Extending TestLookup.

You’re welcome to use Conventional Commits prefixes, short labels such as “fix” or “docs” at the start of the subject. They make release notes easier to write. If people will notice your change, also add a line to the Unreleased section of the changelog.

TestLookup is early, pre-1.0 open-source software under the Apache-2.0 license. A version number in the code doesn’t promise that features or interfaces will stay the same.

Add tests and docs

Add a test that fails without your fix and passes with it, and cover the important ways things can go wrong. Run the tests closest to your change first. Then run the wider package, integration, documentation or deployment checks that your change affects.

In the pull request, list the commands you ran and what they showed. Say which ones used stand-ins for real services, called mocks, and which ran offline. Also say which ran against real services and which ran in the project’s continuous integration (CI) builds.

Before you push, run the full check. CI runs more than the test suites. It also checks the frontend bundle, the theme, the generated reference files and the project’s quality rules.

make push-check           # runs everything CI runs
make push-check-quick     # skips the slow suites
make install-hooks        # runs the full check on every git push

The quick check is only a first pass, so passing it doesn’t mean CI will pass. Frontend unit tests must not make real network requests. Tests use made-up data only, with no real names, hosts, keys or customer data.

If your change alters what the API promises or how people use TestLookup, update the public documentation and the generated reference files. Describe any change that breaks existing setups, and any manual upgrade step, in the upgrade notes.

Open a pull request

Open the pull request against the main branch and fill in the template. It asks what changed, why, how you tested it, your changelog line, and screenshots if you changed what people see on screen.

Reply to review comments. Before the change is merged, combine any small fix-up commits with the commits they fix.

The maintainers aim to reply within a week, but that’s a goal, not a promise. The governance document explains how decisions are made.

Sign off every commit. The sign-off line confirms, under the Developer Certificate of Origin 1.1, that you wrote the change or have the right to contribute it. TestLookup uses this sign-off instead of a contributor license agreement (CLA).

git commit -s             # adds your sign-off line to the commit

A check on every pull request looks for the sign-off. A pull request can be merged only when every commit in it is signed off.

License and policy

Your contribution is licensed under the same Apache-2.0 terms as the rest of the repository. Keep any notices and credits that the code and its dependencies require.

A new dependency must use a license on the project’s approved list. The project doesn’t accept copyleft, source-available or non-commercial licenses.

Every feature people can use is either Core or Experimental. Core features are on by default. Experimental features sit behind an on/off setting that starts off, and they may change or be removed.

This page summarizes the project’s contribution policy. If the policy on GitHub has changed since, the current CONTRIBUTING.md file wins. The code of conduct, the security policy and the license also live in the repository.