Contributing
Contributing to Lakestream, Ursa and Ursa for Apache Kafka (UFK) means choosing the right repository, signing your work, and opening a pull request.
Lakestream, Ursa and Ursa for Apache Kafka (UFK) are developed in the open, in the openlakestream GitHub organization. Bug reports, fixes, documentation, tests, new materializers and feedback on the API are all welcome.
This page is the map across repositories. Each repository's CONTRIBUTING.md is the authoritative source for its rules, and has its build and test steps.
Ways to contribute
- Report a bug or request a feature as an issue in the project's repository.
- Ask a question or share an idea in GitHub Discussions.
- Fix something. Comment on the issue to say you're working on it, so nobody duplicates your work.
- Improve the docs. If something confused you, it will confuse the next person too.
- Write a materializer. Materialize streams into a table format or store that Ursa doesn't support yet. See Write a materializer.
- Shape the API. The Lakestream API is still evolving. Feedback from people building on it is the most useful kind.
Where to talk
| For | Use |
|---|---|
| General questions, or you're not sure which project | Discussions: Q&A |
| Questions about Ursa or the Lakestream API | Ursa Discussions: Q&A |
| Questions about UFK | UFK Discussions: Q&A |
| Design ideas, and proposals before they become a LIP | The project's Discussions: Ideas, for Ursa or UFK |
| Bugs and concrete feature requests | Issues in the project's repository |
| Security vulnerabilities | Report privately, as described in Security |
| Conduct concerns | See the code of conduct |
The projects don't run a Slack workspace or a mailing list, so decisions happen where everyone can read them.
Which repository
| To change | Repository | Contributing guide |
|---|---|---|
The Lakestream API (the lakestream-api module), Ursa, or a materializer | openlakestream/ursa | CONTRIBUTING.md |
| Diskless topics and the Ursa integration in UFK | openlakestream/kafka | CONTRIBUTING.md |
| A Lakestream Improvement Proposal (LIP) | openlakestream/lips | CONTRIBUTING.md |
| The leaderless log protocol specs and their models | openlakestream/leaderless-log-protocol | CONTRIBUTING.md |
| The delivery and ordering harness | openlakestream/streaming-proof | README |
UFK tracks Apache Kafka and keeps its own changes small. A problem that also happens on the Apache Kafka release UFK is built on belongs upstream: follow Apache Kafka's contributing guide. UFK's contributing guide explains how to tell the two apart.
Before you write code
- Small, self-contained changes can go straight to a pull request. Examples: a bug fix with a test, a documentation correction, a typo.
- For anything larger, open an issue or a discussion first. That includes a new feature, a refactor across modules, or a change in behavior. Agreeing on the approach first saves you from writing code that has to be redone.
- Some changes need a LIP: a change that other people build on or operate against, such as a public type in
lakestream-api, an SPI contract, a storage format, or what a Kafka client can observe on a diskless topic. Improvement proposals lists when you need one.
Sign your work
Every commit needs a Developer Certificate of Origin (DCO) sign-off:
git commit -s -m "Fence stream lifecycle operations"The -s flag adds a line such as Signed-off-by: Your Name <you@example.com>. The line certifies that you wrote the change, or otherwise have the right to submit it under the project's license. A DCO check runs on every pull request. If you forgot to sign off, fix the last commit with git commit --amend -s --no-edit, then force-push your branch.
There's no CLA. The DCO sign-off is all the projects ask.
AI assistance
You're welcome to use AI coding tools. The AI policy explains what the projects ask in return. The short version:
- You are the author. You understand every line you submit, you have tested it, and you can explain it.
- Disclose meaningful AI help in the pull request and with an
Assisted-by:commit trailer. - Only a human signs off. An AI tool never adds
Signed-off-by. - A human approves every outward action. Agents don't push, open pull requests or issues, or comment on their own.
- Words you post are yours. Edit AI-drafted text before you post it.
Pull requests
- Fork the repository on GitHub, create a branch for your change, and push it to your fork. For UFK, open the pull request against the default branch, which is named after the Apache Kafka release UFK is built on (
4.3-ursatoday). - Keep each pull request to one logical change. Smaller pull requests get reviewed sooner.
- Fill in the pull request template: what changed and why, compatibility, how you tested it, and AI assistance.
- Update the documentation in the same pull request when you change behavior or a contract.
- Make sure CI passes.
- A code owner for the files you touched reviews and approves the change. Code owners are listed in each repository's
CODEOWNERSfile, and the contributing guides call them maintainers.
Pull requests are squash-merged, so write the title the way you'd write a commit summary: short, and in the imperative mood. In UFK, don't use Apache Kafka's KAFKA-1234: prefixes; they refer to its Jira. If a pull request has been quiet for a while, @-mention one of the code owners for the files you changed.
Build and test
Each repository documents its own toolchain, build, tests and code style: Ursa, UFK and leaderless-log-protocol. To build Ursa from source for use with these docs, see build from source.
License
Lakestream, Ursa and UFK are licensed under the Apache License 2.0, and so is your contribution.