docs: Streamline contributing guide

- Add quick start code block at top
- Lead with local venv setup (primary path)
- Move Codespaces to alternative section
- Remove manual TOC and back-to-top links
- Simplify pre-commit and testing sections
- Link to DOCSTRING_STYLE.md for docstring guidelines

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: dimitri-yatsenko

docs/src/develop.md

@@ -1,202 +1,101 @@
-# Developer Guide
+# Contributing Guide
 
-## Table of Contents
-
-- [Contribute to DataJoint Python Documentation](#contribute-to-datajoint-python-documentation)
-- [Setup Development Environment](#setup-development-environment)
-  - [Prerequisites](#prerequisites)
-  - [With Virtual Environment](#with-virtual-environment)
-  - [With DevContainer](#with-devcontainer)
-  - [Extra Efficiency, Optional But Recommended](#extra-efficiency-optional-but-recommended)
-    - [Pre-commit Hooks](#pre-commit-hooks)
-    - [Integration Tests](#integration-tests)
-    - [VSCode](#vscode)
-      - [Jupyter Extension](#jupyter-extension)
-      - [Debugger](#debugger)
-    - [MySQL CLI](#mysql-cli)
-
-## Contribute to DataJoint Python Documentation
-
-> Contributions to documentations are equivalently important to any code for the community, please help us to resolve any confusions in documentations.
-
-[Here](https://github.com/datajoint/datajoint-python/blob/master/docs/README.md) is the instructions for contributing documentations, or you can find the same instructions at `$PROJECT_DIR/docs/README.md` in the repository.
-
-[Back to top](#table-of-contents)
-
-## Setup Development Environment
-
-> We have [DevContainer](https://containers.dev/) ready for contributors to develop without setting up their environment. If you are familiar with DevContainer, Docker or Github Codespace, this is the recommended development environment for you.
-> If you have never used Docker, it might be easier for you to use a virtual environment through `conda/mamba/venv`, it is also very straightforward to set up.
-
-### Prerequisites
-
-- Clone datajoint-python repository
+## Quick Start
 
 ```bash
-# If you have your SSH key set up with GitHub, you can clone using SSH
-git clone git@github.com:datajoint/datajoint-python.git
-# Otherwise, you can clone using HTTPS
+# Clone the repository
 git clone https://github.com/datajoint/datajoint-python.git
-```
-- If you don't use DevContainer, then either install Anaconda/[Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/install)/Mamba, or just use Python's built-in `venv` module without install anything else.
-
-### With Virtual Environment
+cd datajoint-python
 
-```bash
-# Check if you have Python 3.10 or higher, if not please upgrade
-python --version
-# Create a virtual environment with venv
+# Create virtual environment (Python 3.10+)
 python -m venv .venv
-source .venv/bin/activate
-pip install -e .[dev]
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 
-# Or create a virtual environment with conda
-conda create -n dj python=3.13 # any 3.10+ is fine
-conda activate dj
-pip install -e .[dev]
-```
+# Install with development dependencies
+pip install -e ".[dev]"
 
-[Back to top](#table-of-contents)
+# Install pre-commit hooks
+pre-commit install
 
-### With DevContainer
+# Run tests
+pytest tests
+```
 
-#### Launch Environment
+## Development Environment
 
-Here are some options that provide a great developer experience:
+### Local Setup
 
-- **Cloud-based IDE**: (*recommended*)
-  - Launch using [GitHub Codespaces](https://github.com/features/codespaces) using the option `Create codespace on master` in the codebase repository on your fork.
-  - Build time for a 2-Core codespace is **~6m**. This is done infrequently and cached for convenience.
-  - Start time for a 2-Core codespace is **~2m**. This will pull the built codespace from cache when you need it.
-  - *Tip*: GitHub auto names the codespace but you can rename the codespace so that it is easier to identify later.
-- **Local IDE (VSCode - Dev Containers)**:
-  - Ensure you have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
-  - Ensure you have [Docker](https://docs.docker.com/get-docker/)
-  - Ensure you have [VSCode](https://code.visualstudio.com/)
-  - Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
-  - `git clone` the codebase repository and open it in VSCode
-  - Use the `Dev Containers extension` to `Reopen in Container` (More info in the `Getting started` included with the extension)
-  - You will know your environment has finished loading once you see a terminal open related to `Running postStartCommand` with a final message: `Done. Press any key to close the terminal.`.
-- **Local IDE (Docker Compose)**:
-  - Ensure you have [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
-  - Ensure you have [Docker](https://docs.docker.com/get-docker/)
-  - `git clone` the codebase repository and open it in VSCode
-  - Issue the following command in the terminal to build and run the Docker container: `HOST_UID=$(id -u) PY_VER=3.11 DJ_VERSION=$(grep -oP '\d+\.\d+\.\d+' src/datajoint/version.py) docker compose --profile test run --rm -it djtest -- sh -c 'pip install -qe ".[dev]" && bash'`
-  - Issue the following command in the terminal to stop the Docker compose stack: `docker compose --profile test down`
+Requirements:
 
-[Back to top](#table-of-contents)
+- Python 3.10 or higher
+- MySQL 8.0+ or Docker (for running tests)
 
-## Extra Efficiency, Optional But Recommended
+The `[dev]` extras install all development tools: pytest, pre-commit, black, ruff, and documentation builders.
 
-### Pre-commit Hooks
+### Using Docker for Database
 
-We recommend using [pre-commit](https://pre-commit.com/) to automatically run linters and formatters on your code before committing.
-To set up pre-commit, run the following command in your terminal:
+Tests require a MySQL database. Start one with Docker:
 
 ```bash
-pip install pre-commit
-pre-commit install
+docker compose up -d db
 ```
 
-You can manually run pre-commit on all files with the following command:
+Configure connection (or set environment variables):
 
 ```bash
-pre-commit run --all-files
+export DJ_HOST=localhost
+export DJ_USER=root
+export DJ_PASS=password
 ```
-This will run all the linters and formatters specified in the `.pre-commit-config.yaml` file. If all check passed, you can commit your code. Otherwise, you need to fix the failed checks and run the command again.
 
-> Pre-commit will automatically run the linters and formatters on all staged files before committing. However, if your code doesn't follow the linters and formatters, the commit will fail.
-> Some hooks will automatically fix your problem, and add the fixed files as git's `unstaged` files, you just need to add them(`git add .`) to git's `staged` files and commit again.
-> Some hooks will not automatically fix your problem, so you need to check the pre-commit failed log to fix them manually and include the update to your `staged` files and commit again.
+### Alternative: GitHub Codespaces
 
-If you really don't want to use pre-commit, or if you don't like it, you can uninstall it with the following command:
+For a pre-configured environment, use [GitHub Codespaces](https://github.com/features/codespaces):
 
-```bash
-pre-commit uninstall
-```
+1. Fork the repository
+2. Click "Create codespace on master"
+3. Wait for environment to build (~6 minutes first time, ~2 minutes from cache)
 
-But when you issue a pull request, the same linter and formatter check will run against your contribution, you are going to have the same failure as well. So without pre-commit, you need to **manually run these linters and formatters before committing your code**:
+## Code Quality
 
-- Syntax tests
+### Pre-commit Hooks
 
-The following will verify that there are no syntax errors.
+Pre-commit runs automatically on `git commit`. To run manually:
 
-```
-flake8 datajoint --count --select=E9,F63,F7,F82 --show-source --statistics
+```bash
+pre-commit run --all-files
 ```
 
-- Style tests
+Hooks include:
 
-The following will verify that there are no code styling errors.
+- **ruff** — Linting and import sorting
+- **black** — Code formatting
+- **mypy** — Type checking (optional)
 
-```
-flake8 --ignore=E203,E722,W503 datajoint --count --max-complexity=62 --max-line-length=127 --statistics
-```
-
-The following will ensure the codebase has been formatted with [black](https://black.readthedocs.io/en/stable/).
+### Running Tests
 
-```
-black datajoint --check -v --diff
-```
+```bash
+# Full test suite with coverage
+pytest -sv --cov=datajoint tests
 
-The following will ensure the test suite has been formatted with [black](https://black.readthedocs.io/en/stable/).
+# Single test file
+pytest tests/test_connection.py
 
+# Single test function
+pytest tests/test_connection.py::test_dj_conn -v
 ```
-black tests --check -v --diff
-```
-
-[Back to top](#table-of-contents)
-
-### Integration Tests
-
-The following will verify there are no regression errors by running our test suite of unit and integration tests.
-
-- Entire test suite:
-  ```
-  pytest -sv --cov-report term-missing --cov=datajoint tests
-  ```
-
-- A single functional test:
-  ```
-  pytest -sv tests/test_connection.py::test_dj_conn
-  ```
-- A single class test:
-  ```
-  pytest -sv tests/test_aggr_regressions.py::TestIssue558
-  ```
 
-[Back to top](#table-of-contents)
+## Submitting Changes
 
-### VSCode
+1. Create a feature branch from `master`
+2. Make your changes
+3. Ensure tests pass and pre-commit is clean
+4. Submit a pull request
 
-#### Jupyter Extension
+PRs trigger CI checks automatically. All checks must pass before merge.
 
-Be sure to go through this documentation if you are new to [Running Jupyter Notebooks with VSCode](https://code.visualstudio.com/docs/datascience/jupyter-notebooks#_create-or-open-a-jupyter-notebook).
+## Documentation
 
-#### Debugger
-
-[VSCode Debugger](https://code.visualstudio.com/docs/editor/debugging) is a powerful tool that can really accelerate fixes.
-
-Try it as follows:
-
-- Create a python script of your choice
-- `import datajoint` (This will use the current state of the source)
-- Add breakpoints by adding red dots next to line numbers
-- Select the `Run and Debug` tab
-- Start by clicking the button `Run and Debug`
-
-[Back to top](#table-of-contents)
-
-### MySQL CLI
-
-> Installation instruction is in [here](https://dev.mysql.com/doc/mysql-shell/8.0/en/mysql-shell-install.html)
-
-It is often useful in development to connect to DataJoint's relational database backend directly using the MySQL CLI.
-
-Connect as follows to the database running within your developer environment:
-
-```
-mysql -hdb -uroot -ppassword
-```
+Docstrings use NumPy style. See [DOCSTRING_STYLE.md](https://github.com/datajoint/datajoint-python/blob/master/DOCSTRING_STYLE.md) for guidelines.
 
-[Back to top](#table-of-contents)
+User documentation is maintained at [docs.datajoint.com](https://docs.datajoint.com).