docs: contributing guide (#1970)

* Adds basic contributing guides.
* Simplifies Python development with a Makefile.

python/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to LanceDB Python
+
+This document outlines the process for contributing to LanceDB Python.
+For general contribution guidelines, see [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## Project layout
+
+The Python package is a wrapper around the Rust library, `lancedb`. We use
+[pyo3](https://pyo3.rs/) to create the bindings between Rust and Python.
+
+* `src/`: Rust bindings source code
+* `python/lancedb`: Python package source code
+* `python/tests`: Unit tests
+
+## Development environment
+
+To set up your development environment, you will need to install the following:
+
+1. Python 3.9 or later
+2. Cargo (Rust's package manager). Use [rustup](https://rustup.rs/) to install.
+3. [protoc](https://grpc.io/docs/protoc-installation/) (Protocol Buffers compiler)
+
+Create a virtual environment to work in:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install maturin
+```
+
+### Commit Hooks
+
+It is **highly recommended** to install the pre-commit hooks to ensure that your
+code is formatted correctly and passes basic checks before committing:
+
+```bash
+make develop # this will install pre-commit itself
+pre-commit install
+```
+
+## Development
+
+Most common development commands can be run using the Makefile.
+
+Build the package
+
+```shell
+make develop
+```
+
+Format:
+
+```shell
+make format
+```
+
+Run tests:
+
+```shell
+make test
+make doctest
+```
+
+To run a single test, you can use the `pytest` command directly. Provide the path
+to the test file, and optionally the test name after `::`.
+
+```shell
+# Single file: test_table.py
+pytest -vv python/tests/test_table.py
+# Single test: test_basic in test_table.py
+pytest -vv python/tests/test_table.py::test_basic
+```
+
+To see all commands, run:
+
+```shell
+make help
+```

python/Makefile

@@ -0,0 +1,32 @@
+PIP_EXTRA_INDEX_URL ?= https://pypi.fury.io/lancedb/
+
+help:		## Show this help.
+	@sed -ne '/@sed/!s/## //p' $(MAKEFILE_LIST)
+
+.PHONY: develop
+develop:	## Install the package in development mode.
+	PIP_EXTRA_INDEX_URL=$(PIP_EXTRA_INDEX_URL) maturin develop --extras tests,dev,embeddings
+
+.PHONY: format
+format:		## Format the code.
+	cargo fmt
+	ruff format python
+
+.PHONY: check
+check:		## Check formatting and lints.
+	cargo fmt --check
+	ruff format --check python
+	cargo clippy
+	ruff check python
+
+.PHONY: fix
+fix:		## Fix python lints
+	ruff check python --fix
+
+.PHONY: doctest
+doctest:	## Run documentation tests.
+	pytest --doctest-modules python/lancedb
+
+.PHONY: test
+test:		## Run tests.
+	pytest python/tests -vv --durations=10 -m "not slow"

python/README.md

@@ -8,6 +8,15 @@ A Python library for [LanceDB](https://github.com/lancedb/lancedb).
 pip install lancedb
 ```
 
+### Preview Releases
+
+Stable releases are created about every 2 weeks. For the latest features and bug fixes, you can install the preview release. These releases receive the same level of testing as stable releases, but are not guaranteed to be available for more than 6 months after they are released. Once your application is stable, we recommend switching to stable releases.
+
+
+```bash
+pip install --pre --extra-index-url https://pypi.fury.io/lancedb/ lancedb
+```
+
 ## Usage
 
 ### Basic Example
@@ -20,76 +29,6 @@ results = table.search([0.1, 0.3]).limit(20).to_list()
 print(results)
 ```
 
-## Development
+### Development
 
-LanceDb is based on the rust crate `lancedb` and is built with maturin.  In order to build with maturin
-you will either need a conda environment or a virtual environment (venv).
-
-```bash
-python -m venv venv
-. ./venv/bin/activate
-```
-
-Install the necessary packages:
-
-```bash
-python -m pip install .[tests,dev]
-```
-
-To build the python package you can use maturin:
-
-```bash
-# This will build the rust bindings and place them in the appropriate place
-# in your venv or conda environment
-maturin develop
-```
-
-To run the unit tests:
-
-```bash
-pytest
-```
-
-To run the doc tests:
-
-```bash
-pytest --doctest-modules python/lancedb
-```
-
-To run linter and automatically fix all errors:
-
-```bash
-ruff format python
-ruff --fix python
-```
-
-If any packages are missing, install them with:
-
-```bash
-pip install <PACKAGE_NAME>
-```
-
-___
-For **Windows** users, there may be errors when installing packages, so these commands may be helpful:
-
-Activate the virtual environment:
-
-```bash
-. .\venv\Scripts\activate
-```
-
-You may need to run the installs separately:
-
-```bash
-pip install -e .[tests]
-pip install -e .[dev]
-```
-
-`tantivy` requires `rust` to be installed, so install it with `conda`, as it doesn't support windows installation:
-
-```bash
-pip install wheel
-pip install cargo
-conda install rust
-pip install tantivy
-```
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for information on how to contribute to LanceDB.