docs,chore: improve development documentation and fix tooling

DEVELOPMENT.md

@@ -1,32 +1,58 @@
 # Setting up a Development Environment
 
 This document details how to set up a local development environment that will
-allow you to contribute changes to the project.
+allow you to contribute changes to langchain-postgres.
 
-Acquire sources and create virtualenv.
+## Setup
+
+Clone the repository and create a virtualenv:
 ```shell
 git clone https://github.com/langchain-ai/langchain-postgres
 cd langchain-postgres
 uv venv --python=3.13
 source .venv/bin/activate
 ```
 
-Install package in editable mode.
+Install dependencies, required for local development:
 ```shell
-poetry install --with dev,test,lint
+uv sync --group test
 ```
 
-Start PostgreSQL/PGVector.
+Start a PostgreSQL instance with `pgvector` extension:
+```shell
+docker compose up -d
+```
+
+## Testing
+
+Run all unit tests:
 ```shell
-docker run --rm -it --name pgvector-container \
-  -e POSTGRES_USER=langchain \
-  -e POSTGRES_PASSWORD=langchain \
-  -e POSTGRES_DB=langchain \
-  -p 6024:5432 pgvector/pgvector:pg16 \
-  postgres -c log_statement=all
+make test
 ```
 
-Invoke test cases.
+Run unit tests from a single file:
 ```shell
-pytest -vvv
+make test TEST_FILE=tests/unit_tests/v2/test_engine.py
 ```
+
+Run all unit tests in watch mode:
+```shell
+make test_watch
+```
+
+## Linting and formatting
+
+Format all files using `ruff` and fix errors:
+```shell
+make format
+```
+
+Lint all files using `ruff` and `mypy`:
+```shell
+make lint
+```
+
+Spell check all files and fix errors:
+```shell
+make spell_fix
+```

Makefile

@@ -23,7 +23,7 @@ test_watch:
 
 # Define a variable for Python and notebook files.
 lint format: PYTHON_FILES=.
-lint_diff format_diff: PYTHON_FILES=$(shell git diff --relative=. --name-only --diff-filter=d master | grep -E '\.py$$|\.ipynb$$')
+lint_diff format_diff: PYTHON_FILES=$(shell git diff --relative=. --name-only --diff-filter=d main | grep -E '\.py$$|\.ipynb$$')
 
 lint lint_diff:
 	[ "$(PYTHON_FILES)" = "" ] || uv run ruff format $(PYTHON_FILES) --diff
@@ -47,12 +47,17 @@ spell_fix:
 help:
 	@echo '===================='
 	@echo '-- LINTING --'
-	@echo 'format                       - run code formatters'
-	@echo 'lint                         - run linters'
-	@echo 'spell_check                 	- run codespell on the project'
-	@echo 'spell_fix                		- run codespell on the project and fix the errors'
+	@echo 'format                               - run code formatters on entire project and fix errors'
+	@echo 'format_diff                          - run code formatters on changed files (compared to main) and fix errors'
+	@echo 'format PYTHON_FILES=<path>           - run code formatters on specific path and fix errors'
+	@echo 'lint                                 - run linters on entire project'
+	@echo 'lint_diff                            - run linters on changed files (compared to main)'
+	@echo 'lint PYTHON_FILES=<path>             - run linters on specific path'
+	@echo 'spell_check                          - run codespell on entire project'
+	@echo 'spell_fix                            - run codespell on entire project and fix errors'
 	@echo '-- TESTS --'
-	@echo 'coverage                     - run unit tests and generate coverage report'
-	@echo 'test                         - run unit tests'
-	@echo 'test TEST_FILE=<test_file>   - run all tests in file'
+	@echo 'test                                 - run all unit tests'
+	@echo 'test TEST_FILE=<test_file>           - run unit tests from file'
+	@echo 'test_watch                           - run all unit tests (watch mode)'
+	@echo 'test_watch TEST_FILE=<test_file>     - run unit tests from file (watch mode)'
 	@echo '-- DOCUMENTATION tasks are from the top-level Makefile --'

docker-compose.yml

@@ -16,7 +16,7 @@ services:
       test:
         [
           "CMD-SHELL",
-          "psql postgresql://langchain:langchain@localhost/langchain --command 'SELECT 1;' || exit 1",
+          "psql postgresql://langchain:langchain@localhost/langchain_test --command 'SELECT 1;' || exit 1",
         ]
       interval: 5s
       retries: 60