Contribution Guidelines

How to contribute to Texera code and documentation.

Thank you for your interest in contributing to Texera! This guide explains how to contribute to both Texera’s codebase and documentation.
We follow a fork-based workflow and adopt the Conventional Commits standard for commit messages.

Contributing to Texera

Texera welcomes contributions from everyone — whether you’re fixing a small bug, improving documentation, or adding new features.


👥 Roles in the Project

RoleKey PermissionsHow to Join
ContributorSubmit issues & PRs, join discussionsStart contributing — no formal process
CommitterMerge PRs, push code, vote on code changesNominated by PPMC based on quality contributions
PPMC MemberGovernance, release voting, new committer approvalsVoted by existing PPMC members
MentorGuide project and ensure Apache complianceAppointed by the Incubator PMC

🛠 How to Contribute Code

1. Fork the Repository

Fork the Texera repository on GitHub and clone it locally.

2. Find or Open an Issue

  • Pick an existing issue or create a new one describing your proposal or bug.
  • Discuss your approach with committers before coding to reach consensus.

3. Create and Submit a Pull Request

  • Develop in a new branch of your fork.

    Modifying the SQL schema?
    Be sure to update sql/changelog.xml by adding a new <changeSet> element.

  • When ready, submit a PR to the main Texera repository.

  • Allow edits from maintainers to let committers make small fixes if needed.

PR Title and Commit Format

We use Conventional Commits:

  • Example PR titles:
    • feat: add new join operator
    • fix(frontend): resolve workflow panel crash
    • chore(deps): bump dependency versions
  • The PR title becomes the final squashed commit message upon merge.

A scope names the module the change lands in — amber, pyamber, frontend, agent-service, file-service, and so on. Use the module’s own name rather than an informal synonym, and when a PR spans modules, scope it to the one carrying the substantive change.

Pick the type by what happens to the behavior, not by how large the change is:

Your changeType
A functionality worked before and no longer doesfix
A functionality or a form of support never existed and you are adding itfeat
A functionality exists and you are removing support for itfeat
A functionality is reworked in a way that intentionally changes user-facing behaviorfeat
The change leaves the user-facing behavior unchangedrefactor

Behavior is defined by the code, not by what a document or an old PR description says the code does. A functionality that was never implemented does not exist, so implementing it is a feat even when the docs already described it as present.

refactor claims the user-facing behavior is identical. A test that pins a user-facing API must keep passing untouched — changing one of its assertions means the behavior moved, so the PR is a feat or a fix. A test that pins internals mirrors the implementation and may be rewritten alongside the code it mirrors.

Test and dependency PRs take the titles below. Where the table shows a two-part scope, it is written as <type>(<area>, <module>): <description>:

Your changeTitle
A test-only PR — adding or updating teststest(<module>): ...
Repairing a broken or flaky testfix(test, <module>): ...
A dependency bump that patches a CVEfix(deps, <module>): ...
Any other dependency bumpchore(deps, <module>): ...

Omit the module for bumps that span modules. GitHub Actions bumps are dependency bumps too and take the ci module — chore(deps, ci): ..., or fix(deps, ci): ... when the bump patches a CVE — which is the form Renovate opens them with. Reserve a bare ci: ... for hand-written CI and workflow changes.

A PR targeting a release branch appends the version as the last scope component — a backport of fix(deps, frontend): ... to release/v1.2 becomes fix(deps, frontend, v1.2): .... Never put a version tag on a PR targeting main.

PR Description Should Include:

  • Purpose: use Closes #1234 to auto-close an issue.
  • Summary: short overview of your changes.
  • Optional: design document, technical diagram, or screenshots.

Avoid including:

  • Local config files (e.g., python_udf.conf)
  • Secrets or credentials
  • Binary or build artifacts

🧪 Testing and Quality Checks

Backend (Scala)

  1. Run lint:
    sbt "scalafixAll --check"
    
    Fix with:
    sbt scalafixAll
    
  2. Run formatter:
    sbt scalafmtCheckAll
    
    Fix with:
    sbt scalafmtAll
    
  3. Execute tests:
    sbt test
    

For IntelliJ users: ensure the working directory matches the module (amber for engine tests, the repo root for services).

Frontend (Angular)

  1. Run unit tests:
    cd frontend
    ng test --watch=false
    
  2. Format code:
    yarn format:fix
    

Write .spec.ts tests for new functionality to ensure future safety.


🔍 Pull Request Review Process

  1. Request a committer to review your PR.
  2. Add labels (e.g., fix, enhancement, docs).
  3. Wait for CI to pass (GitHub Actions).
  4. Mark your PR as draft if it’s not ready.
  5. Once approved, a committer will merge your PR.

📝 Apache License Header

All new files must include the Apache License header.
To automate this in IntelliJ:

  1. Go to Settings → Editor → Copyright → Copyright Profiles.
  2. Create a profile named Apache and add:
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements. See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership...
    
  3. Set this as the default profile for the project.

✍️ Contributing to Documentation

Texera uses Hugo and the Docsy theme to build its website.
All documentation is stored in the Texera GitHub repository.

Quick Steps

  1. Click Edit this page at the top of any doc page to edit directly on GitHub.
  2. Make your edits and open a Pull Request.
  3. The site auto-deploys a preview for review via Netlify.
  4. Wait for approval and merge.

Preview Locally

To preview locally:

hugo server

Visit http://localhost:1313 to view the site as you edit.


📚 Resources