Skip to main content
This guide covers the pull request process for contributing to Vespa, including best practices, review requirements, and testing guidelines.

​
Creating a Pull Request

​
Commit Best Practices

Please follow best practices for creating git commits:
1

Write Clear Commit Messages

Use descriptive commit messages that explain what changes were made and why.
# Good
git commit -m "Add support for tensor slicing in ranking expressions"

# Bad
git commit -m "fix bug"
2

Make Atomic Commits

Each commit should represent a single logical change. Don’t mix unrelated changes in one commit.
3

Test Before Committing

Ensure your changes build successfully and pass all relevant tests before creating a commit.

​
Submitting Your Pull Request

When your code is ready to be submitted:
  1. Push your changes to a branch in your fork
  2. Create a pull request against the Vespa repository
  3. Fill out the pull request template
All pull requests include a license confirmation template that you must agree to.

​
Code Review Requirements

​
Reviewer Selection

Every pull request must be approved by a Vespa Committer who is different from the author.
1

Find the Right Reviewer

Look for the OWNERS file upward in the source tree from where you’re making changes. The OWNERS have special responsibility for their code areas.
2

Request Review

Request a review from an appropriate owner or committer familiar with the area of code you’re modifying.
3

Get Approval

The reviewer can approve by:
  • Clicking “Approve” in the GitHub UI
  • Making a comment indicating agreement
  • Merging the PR (approval can happen before or during merge)

​
Review Process

Reviewers evaluate:
  • Code quality: Is the code well-structured, readable, and maintainable?
  • Correctness: Does the code do what it’s supposed to do?
  • Testing: Are there appropriate tests for the changes?
  • API compatibility: Do changes maintain backward compatibility (see versioning)?
  • Documentation: Are public APIs documented? Is the change documented if needed?
  • Performance: Are there any performance implications?
When you receive feedback:
  1. Address each comment thoughtfully
  2. Push new commits to your branch (they’ll appear in the PR automatically)
  3. Reply to comments to explain your changes or reasoning
  4. Mark conversations as resolved when addressed
  5. Request re-review when ready

​
Approval Authority

Only Vespa Committers can approve and merge pull requests. The committer must be different from the PR author.
As a rule, approval should happen before merging, but this is not strictly required as the approver can revert if needed.

​
Testing Requirements

​
Building and Testing

Before submitting your PR, ensure your changes build and pass tests: 
# Build Java modules
export MAVEN_OPTS="-Xms128m -Xmx1024m"
mvn install --threads 1C

​
ABI Compatibility Verification

For Java APIs, ABI (Application Binary Interface) compatibility is automatically verified during the Maven build:
The build will fail if you make incompatible changes to public APIs or if you add to public APIs without updating the ABI spec.
If you need to add to public APIs:
  1. Ensure there’s a good reason for the addition
  2. Update the ABI spec as instructed in the error message from the build
See the versioning guide for more details on API compatibility.

​
Continuous Integration

All pull requests are automatically built and tested by Vespa’s continuous integration system:
  • View build results at factory.vespa.ai
  • Builds must pass before merging
  • Failed builds will show details about what went wrong
Do not merge pull requests with failing CI builds unless you have a very good reason and explicit approval from a senior committer.

​
Governance and Disputes

Vespa follows a governance model defined in GOVERNANCE.md.

​
Decision Making

While formal authority exists as a fallback, decisions are usually made by reaching consensus based on technical merit, with no regard to status or formal role.
The community values:
  • Disagreement as healthy (diversity of perspectives leads to better decisions)
  • Technical arguments over formal authority
  • Building consensus through discussion

​
The Vespa Board

The Vespa Board has final authority over all decisions, including:
  • Whether to merge (or keep) a PR in the event of any dispute
  • Who should be committers and board members
  • Changes to the governance policy
The board consists of 4 people and makes decisions by majority vote:
  • Jon Bratseth (bratseth) - leader
  • Kristian Aune (kkraune)
  • Kim Johansen (johans1)
  • Frode Lundgren (frodelu)

​
Release Process

Vespa releases the master branch four times a week (Monday through Thursday morning CET).
This means:
  • Your merged PR will be in production within days
  • The master branch should always work
  • Test thoroughly before merging
  • Be available to help if issues arise after your change is released

​
Next Steps

Versioning Guidelines

Learn about API compatibility and semantic versioning

Contributing Guide

Back to the main contributing guide

Build docs developers (and LLMs) love

Get started for freeTalk to us