Thank you for your interest in contributing to DefraDB! You're about to join a wave of innovation in decentralized and powerful databases. Every contribution makes a difference - whether it's reporting a bug, improving documentation, suggesting a feature, or writing code.
Note
💡 New here? The quickest way to get started is to join our Discord community and say hello. We're happy to help you find the right place to contribute!
📑 Table of Contents (click to expand)
Caution
Please do NOT file a public issue for security vulnerabilities.
If you discover a security vulnerability, please disclose it responsibly by emailing security@source.network. Our security team will respond within 24 hours.
For full details, see our Security Policy.
You don't need to be an expert in all of these to contribute - many contributions don't require programming at all! But these resources may be useful depending on what you'd like to work on:
| Resource | Purpose | |
|---|---|---|
| 🔀 | Git | Version control basics |
| 📘 | Project Docs | Features & architecture |
| 🐹 | Go | Primary language |
| 🦀 | Cargo/rustc | WASM lens modules |
✅ Required to build and run DefraDB:
| Tool | Notes |
|---|---|
| Go | Check go.mod for the required version |
| Cargo/rustc | Via rustup, needed for WASM lens modules |
💡 Optional (needed for specific features/tests):
| Tool | When You Need It |
|---|---|
| Vera | Working on access control features |
| Ollama | AI/vector embedding tests |
| Make | Convenient but not required - you can run go commands directly |
Clone, build, and run:
git clone https://github.com/sourcenetwork/defradb.git
cd defradb
make startTip
Refer to the README.md and project documentation for detailed usage examples.
The overall project documentation is at docs.source.network, with its source at github.com/sourcenetwork/docs.source.network.
📄 View code documentation locally
Go doc comments can be viewed as a website:
go install golang.org/x/pkgsite/cmd/pkgsite@latest
cd your-path-to/defradb/
pkgsite
# open http://localhost:8080/github.com/sourcenetwork/defradbSee go.dev/doc/comment for Go doc comment guidelines.
| Reference | Location |
|---|---|
| 🌐 HTTP API docs | docs/website/references/http/openapi.json |
| 💻 CLI docs | docs/website/references/cli/ |
| 📄 Man pages | Generate with make docs:manpages → build/man/ |
Found a bug? Here's how to report it:
-
🔍 Search first - check existing issues to avoid duplicates.
-
📝 Create a new issue - go to github.com/sourcenetwork/defradb/issues, click "New issue", and select Bug Report.
-
📋 Include helpful details:
What to Include Example Clear description "Queries with nested filters return empty results" Steps to reproduce "1. Add schema... 2. Create document... 3. Query with..." Expected vs actual "Expected 3 results, got 0" Platform info Use defradb version
Tip
The more detail you provide, the faster we can fix it!
Have an idea? Start a Feature Request discussion. Explain the problem you're solving and why the enhancement would be useful.
Tip
For significant changes, discuss your approach with the team before writing code. This saves effort and ensures alignment with the project direction.
We use the Git Fork Flow for all contributions:
| Step | Action |
|---|---|
| 🍴 1 | Fork the repository on GitHub |
| 📥 2 | Clone your fork and create a feature branch |
| 💻 3 | Make your changes |
| ✅ 4 | Run checks - make lint, make test, etc. (see Testing) |
| 📬 5 | Open a pull request targeting the develop branch |
We follow issue-driven development - every pull request must be linked to one or more issues. If no issue exists, create one first.
Link an issue using resolving keywords in your PR description:
| Keyword | Example |
|---|---|
close / closes / closed |
Closes #123 |
fix / fixes / fixed |
Fixes #456 |
resolve / resolves / resolved |
Resolves #789 |
📋 Example PR description
## Relevant issue(s)
Resolves #123The PR template has a
Relevant issue(s)section for this.
PR titles follow our own convention, close to and inspired by Conventional Commits (but not identical to it): <label>: <Description>
Available labels:
| Label | Meaning | Example | |
|---|---|---|---|
feat |
✨ | New feature | feat: Add document encryption |
fix |
🐛 | Bug fix | fix: Resolve API timeout issue |
refactor |
♻️ | Code refactoring | refactor: Simplify query parser |
docs |
📖 | Documentation | docs: Update API reference |
test |
🧪 | Testing | test: Add P2P sync tests |
ci |
🔧 | CI/CD changes | ci: Update lint workflow |
chore |
🧹 | Maintenance | chore: Update dependencies |
perf |
⚡ | Performance | perf: Optimize index lookups |
tools |
🔨 | Tooling | tools: Add benchstat script |
bot |
🤖 | Automated (bot only) | bot: Bump go version |
Rules:
| Rule | ||
|---|---|---|
| 1️⃣ | Colon + single space after label | ✅ fix: Resolve issue ❌ fix:Resolve issue |
| 2️⃣ | Description starts with capital letter | ✅ docs: Improve README ❌ docs: improve README |
| 3️⃣ | Description should start with an action verb | Add, Update, Fix, Remove, Refactor... |
| 4️⃣ | Last character must be alphanumeric | No trailing . ) or special characters |
| 5️⃣ | Title must not exceed 60 characters (except bot) |
Keep it concise! |
| 6️⃣ | Optional: suffix the label with (i) to mark an internal change (no user-facing impact) - it is left out of the release changelog |
docs(i): Update contributing guidelines |
📌 More examples in
tools/scripts/scripts_test.sh.
First-time contributors will be asked to sign the Contributor License Agreement (CLA). The CLA bot will comment on your PR with instructions.
Request a review from the database-team. After receiving feedback, please try to respond within two weeks to keep the conversation moving.
Reviewers prefix their comments with labels inspired by Conventional Comments to clarify intent and whether a comment is blocking, see the Commenting Etiquette guide for what each label means and what action is expected.
Important
A PR is ready to merge when:
- ✅ All CI checks are passing
- 👍 At least one approval
- 🚫 No
DO NOT MERGElabel - 🔄 Rebased with the upstream
developbranch
We use Squash and Merge - all commits get squashed into one. Your PR title becomes the commit message, so make sure it follows the title format.
Once approved and CI passes, let a maintainer know and they'll merge it for you.
make test # Run unit and integration tests
make lint # Run lintersBenchmarks can be found in the tests/bench/ directory.
Tip
If make isn't available, you can run go test ./... directly.
We'd love to hear from you!
| Channel | Purpose | |
|---|---|---|
| 💬 | Discord | Real-time chat & Q&A |
| X | Updates & announcements | |
| 💻 | Discussions | Feature ideas & long-form chats |
🙏 Thank you for contributing to DefraDB!
Together, we're building the future of decentralized databases 🚀