mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-30 15:26:52 +00:00
Will JonesandClaude Opus 5.5
4d7a64712f
## Summary Adopts the product terminology guide across the docs site pages, SDK docstrings and error messages. "LanceDB OSS" and local mode become **LanceDB Embedded**. "Remote" as the execution model becomes **LanceDB Distributed**, which LanceDB Enterprise provides. Where free vs paid is the point, pages contrast "LanceDB Embedded (open source)" with "LanceDB Enterprise". This is a first trial of the Embedded name, so reviewers can judge it in context. - **Embedded vs Distributed** for where execution runs (`optimize()`, consistency, branching, maintenance). Main pages define it once: "LanceDB Enterprise runs LanceDB Distributed: …" - **LanceDB Cloud** is kept only for legacy-Cloud specifics (`db://` region, the brute-force KNN limit) and marked legacy. "Cloud and Enterprise" becomes Enterprise or Distributed. - **Plan executor** becomes "executor" or the fleet name. - **Error messages** change, e.g. `optimize is not supported for remote tables.` → `... in LanceDB Distributed.` Tests that match on them are updated. - **Vale rules** (`EmbeddedName`, `OSSProduct`, `RemoteExecution`, `DistributedEnterprise`, `LegacyCloud`, `InternalNames`) enforce the terms in prose. Unchanged: identifiers (`availability.oss`, the `remote` module and feature, `RemoteTable`, `db://`), heading anchors, internal code comments, and Geneva. ## Evidence - Rust lib tests for the changed messages and the Python tests in `test_remote_db.py`, `test_materialized_views.py` and `test_table.py` pass locally. - Not run locally: - The Node tests: `remote.test.ts` and `table.test.ts` have updated assertions. - Vale. - The `experimental_functions`-marked materialized-view tests. - `docs/src` API reference was hand-edited to match the docstrings rather than regenerated. ## Merge Risk **Door:** two-way; prose and message text only. **Blast Radius:** `docs`, `error-messages`: callers matching on old error strings would break. Companion PRs: lancedb/docs (assembler labels, STYLE.md) and sophon (Enterprise pages). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
201 lines
8.4 KiB
Markdown
201 lines
8.4 KiB
Markdown
# Contributing to LanceDB
|
|
|
|
LanceDB is an open-source project and we welcome contributions from the community.
|
|
This document outlines the process for contributing to LanceDB.
|
|
|
|
## Reporting Issues
|
|
|
|
If you encounter a bug or have a feature request, please open an issue on the
|
|
[GitHub issue tracker](https://github.com/lancedb/lancedb).
|
|
|
|
## Picking an issue
|
|
|
|
We track issues on the GitHub issue tracker. If you are looking for something to
|
|
work on, check the [good first issue](https://github.com/lancedb/lancedb/contribute) label. These issues are typically the best described and have the smallest scope.
|
|
|
|
If there's an issue you are interested in working on, please leave a comment on the issue. This will help us avoid duplicate work. Additionally, if you have questions about the issue, please ask them in the issue comments. We are happy to provide guidance on how to approach the issue.
|
|
|
|
## Configuring Git
|
|
|
|
First, fork the repository on GitHub, then clone your fork:
|
|
|
|
```bash
|
|
git clone https://github.com/<username>/lancedb.git
|
|
cd lancedb
|
|
```
|
|
|
|
Then add the main repository as a remote:
|
|
|
|
```bash
|
|
git remote add upstream https://github.com/lancedb/lancedb.git
|
|
git fetch upstream
|
|
```
|
|
|
|
## Setting up your development environment
|
|
|
|
We have development environments for Python, Typescript, and Java. Each environment has its own setup instructions.
|
|
|
|
* [Python](python/CONTRIBUTING.md)
|
|
* [Typescript](nodejs/CONTRIBUTING.md)
|
|
<!-- TODO: add Java contributing guide -->
|
|
* [Documentation](docs/README.md)
|
|
|
|
|
|
## Best practices for pull requests
|
|
|
|
For the best chance of having your pull request accepted, please follow these guidelines:
|
|
|
|
1. Unit test all bug fixes and new features. Your code will not be merged if it
|
|
doesn't have tests.
|
|
1. If you change the public API, update the documentation in the `docs` directory.
|
|
1. Aim to minimize the number of changes in each pull request. Keep to solving
|
|
one problem at a time, when possible.
|
|
1. Before marking a pull request ready-for-review, do a self review of your code.
|
|
Is it clear why you are making the changes? Are the changes easy to understand?
|
|
1. Use [conventional commit messages](https://www.conventionalcommits.org/en/) as pull request titles. Examples:
|
|
* New feature: `feat: adding foo API`
|
|
* Bug fix: `fix: issue with foo API`
|
|
* Documentation change: `docs: adding foo API documentation`
|
|
1. If your pull request is a work in progress, leave the pull request as a draft.
|
|
We will assume the pull request is ready for review when it is opened.
|
|
1. When writing tests, test the error cases. Make sure they have understandable
|
|
error messages.
|
|
|
|
## Project structure
|
|
|
|
The core library is written in Rust. The Python, Typescript, and Java libraries
|
|
are wrappers around the Rust library.
|
|
|
|
* `src/lancedb`: Rust library source code
|
|
* `python`: Python package source code
|
|
* `nodejs`: Typescript package source code
|
|
* `node`: **Deprecated** Typescript package source code
|
|
* `java`: Java package source code
|
|
* `docs/src`: SDK reference, built with mkdocs
|
|
* `docs/web`: website guides for LanceDB Embedded and the APIs used by both Embedded and Distributed
|
|
* `docs/web-tests`: the tests the documentation's code examples are extracted from
|
|
|
|
## Documentation
|
|
|
|
Update the docs in the same pull request as the behavior they describe. You can
|
|
merge docs before a feature launches; keep the unfinished material hidden until
|
|
it is ready for readers.
|
|
|
|
### Choose the right place
|
|
|
|
- `docs/web/` holds website guides for LanceDB Embedded and the APIs used by both
|
|
Embedded and Distributed.
|
|
- `docs/src/` holds the SDK reference. See [docs/README.md](docs/README.md) for
|
|
its build and API-generation instructions.
|
|
- `docs/web-tests/` and `rust/lancedb/tests/` hold tests used to generate the
|
|
website's code examples.
|
|
|
|
Document SDK APIs here, and explain which operations work in Embedded and Distributed.
|
|
Put Enterprise-specific deployment and operating instructions in the Enterprise
|
|
documentation.
|
|
|
|
Some pages are placeholders that the website build replaces with an Enterprise
|
|
page. Changes to a placeholder won't appear on the combined site. Put
|
|
instructions that both products need on a separate page and link to it.
|
|
|
|
### Preview and check your change
|
|
|
|
From the repository root:
|
|
|
|
```bash
|
|
npm i -g mint@4.2.888
|
|
(cd docs/web && mint dev)
|
|
```
|
|
|
|
This previews this checkout, including your uncommitted changes. It doesn't
|
|
include the other documentation sources or render the availability labels.
|
|
Use the [combined preview](https://github.com/lancedb/docs#development) when
|
|
checking Enterprise replacements or links to pages from another source.
|
|
Staging shows saved release editions, so it won't show a new source change
|
|
just because that change merged.
|
|
|
|
Follow the [style guide](https://github.com/lancedb/docs/blob/main/STYLE.md).
|
|
[Vale](https://vale.sh) checks wording, names and punctuation using the
|
|
[bundled LanceDB rules](.github/vale/README.md). Pull requests show suggestions
|
|
on the lines they change. With Vale 3.24.0 installed, check a page locally with:
|
|
|
|
```bash
|
|
vale docs/web/indexing/vector-index.mdx
|
|
```
|
|
|
|
Keep existing `{#anchor}` values when changing headings, so links to those
|
|
sections keep working. Give new headings stable anchors. For links in rendered
|
|
components, write the path directly, such as `href="/quickstart"`, and spell out
|
|
attributes rather than using property spreads. That lets versioned docs keep
|
|
links inside the selected edition. Code examples aren't subject to this rule.
|
|
|
|
### Code examples
|
|
|
|
Edit the test that produces an example, then regenerate its snippet. The
|
|
sources are `docs/web-tests/{py,ts,rs}`, `docs/web-tests/blob-v2/{py,ts,rs}` and
|
|
`rust/lancedb/tests`. Run this from the repository root:
|
|
|
|
```bash
|
|
uv run docs/web-tests/mdx_snippets_gen.py \
|
|
-s docs/web-tests/py -s docs/web-tests/ts -s docs/web-tests/rs \
|
|
-s docs/web-tests/blob-v2/py -s docs/web-tests/blob-v2/ts -s docs/web-tests/blob-v2/rs \
|
|
-s rust/lancedb/tests -o docs/web/snippets
|
|
```
|
|
|
|
Run the tests for the examples you changed; generating a snippet doesn't run
|
|
its example. Review the generated diff and commit only the relevant snippets
|
|
with their tests. Don't assume the PR checks execute every documentation
|
|
example.
|
|
|
|
### Say where a feature works
|
|
|
|
Use `availability` in a page's frontmatter to describe the support covered by
|
|
that page. Each product (`oss` for LanceDB Embedded, `enterprise` for LanceDB
|
|
Enterprise) is either `available` or `unavailable`; use the summary
|
|
and body for setup requirements, SDK differences and unsupported operations.
|
|
For example, a page about signing in to Enterprise could declare:
|
|
|
|
```yaml
|
|
availability:
|
|
oss: unavailable
|
|
enterprise: available
|
|
summary: >-
|
|
These sign-in instructions apply to LanceDB Enterprise. LanceDB
|
|
Embedded has no server to sign in to.
|
|
```
|
|
|
|
Check these claims with the feature owner. Don't use `varies`, treat an API
|
|
stub as working support, or mark a supported feature unavailable just because
|
|
it needs configuration. If one label can't describe the whole page accurately,
|
|
make the page's scope narrower and explain the differences.
|
|
|
|
Assembly turns this declaration into a page label and, for a feature supported
|
|
by only one product, a sidebar tag. Don't add those badges by hand. Availability
|
|
labels do not hide unreleased content.
|
|
|
|
### Write docs before launch
|
|
|
|
You don't need to hold a documentation PR until launch. Use these controls:
|
|
|
|
- For a whole page, add its path to `docs/web/.mintignore`. Leave it out of
|
|
`docs/web/docs.json`, redirects and links from published pages. Removing a
|
|
sidebar entry alone doesn't hide a page.
|
|
- For a section, wrap it in an MDX comment, `{/* ... */}`, with a note such as
|
|
`Draft for the Feature X release.` Put draft table rows and list items in a
|
|
comment below the table or list, not between entries.
|
|
|
|
Drafts remain in the source. Use them to avoid advertising an unfinished
|
|
feature, not to keep information confidential. See
|
|
[Writing docs before release](https://github.com/lancedb/docs#writing-docs-before-release)
|
|
for examples and how to preview a draft.
|
|
|
|
Before the intended release, remove the draft controls, restore the navigation
|
|
and links, and check the result. Those changes must be in the source commit the
|
|
edition uses. A later change to `main` doesn't update an edition already saved.
|
|
For a mistake in an existing edition, fix the source and request a
|
|
[recorded correction](https://github.com/lancedb/docs#correcting-a-saved-edition).
|
|
|
|
## Release process
|
|
|
|
For information on the release process, see: [release_process.md](release_process.md)
|