docs: separate maintainer guidance from user docs

Author: qartik

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thank you for your interest in contributing! We welcome contributions from the c
 
 ## Getting Started
 
-See the [Development section](README.md#development) in the README for setup instructions, testing, and build processes.
+See [DEVELOPMENT.md](DEVELOPMENT.md) for setup instructions, test commands, build processes, and LLVM maintenance guidance. For release notes, see [CHANGELOG.md](CHANGELOG.md).
 
 ## How to Contribute
 
@@ -70,12 +70,6 @@ type(scope): brief description
 
 ## Testing
 
-See [README Testing section](README.md#testing) for details on:
-
-- Running the test suite
-- Testing individual files
-- Simulation testing with Selene
-
 Always add tests for new features and ensure all tests pass before submitting a PR.
 
 ## Documentation

DEVELOPMENT.md

@@ -0,0 +1,116 @@
+# Development Notes
+
+## Setup
+
+The default development toolchain is tracked in `rust-toolchain.toml` and follows the latest stable Rust release. The minimum supported Rust version (MSRV) is tracked separately in `Cargo.toml` and wheel-build settings.
+
+```sh
+# Clone the repository
+git clone https://github.com/quantinuum/qir-qis.git
+cd qir-qis
+
+# Install LLVM 21 (macOS/Homebrew example)
+brew install llvm@21
+if [ "$(uname -m)" = "arm64" ]; then
+  export LLVM_SYS_211_PREFIX=/opt/homebrew/opt/llvm@21
+else
+  export LLVM_SYS_211_PREFIX=/usr/local/opt/llvm@21
+fi
+
+# Install Rust dependencies and build
+cargo build
+
+# Install Python dependencies
+uv sync
+```
+
+## Building
+
+```sh
+# Build Rust binary
+LLVM_SYS_211_PREFIX=${LLVM_SYS_211_PREFIX:-/opt/homebrew/opt/llvm@21} \
+cargo build --release
+
+# Build Python package
+LLVM_SYS_211_PREFIX=${LLVM_SYS_211_PREFIX:-/opt/homebrew/opt/llvm@21} \
+uv run maturin build --release
+```
+
+## Testing
+
+Tests require [cargo-nextest](https://nexte.st/docs/installation/pre-built-binaries/).
+
+```sh
+# Run all tests
+LLVM_SYS_211_PREFIX=${LLVM_SYS_211_PREFIX:-/opt/homebrew/opt/llvm@21} \
+make test
+
+# Or directly with the same target as `make test`
+LLVM_SYS_211_PREFIX=${LLVM_SYS_211_PREFIX:-/opt/homebrew/opt/llvm@21} \
+cargo nextest run --all-targets --all-features
+```
+
+### QIR Fixtures
+
+```sh
+# Compile a single QIR file
+make compile FILE=tests/data/adaptive.ll
+
+# Compile all test files
+make allcompile
+```
+
+### Simulation
+
+Test the compiled QIS using [Selene quantum simulator](https://docs.quantinuum.com/selene/).
+
+```sh
+# Simulate a single file (runs 5 shots by default)
+make sim FILE=tests/data/adaptive.ll
+
+# Simulate all test files
+make allsim
+```
+
+### Code Quality
+
+```sh
+# Run linters
+make lint
+```
+
+`make lint` runs:
+
+- `prek` pre-commit checks
+- `typos`
+- `cargo clippy`
+
+### Python Stubs
+
+After modifying the Python API:
+
+```sh
+make stubs
+```
+
+This updates `qir_qis.pyi` with the latest type signatures.
+
+## Updating LLVM
+
+For an LLVM bump, update:
+
+1. `LLVM_VERSION` in `.github/workflows/CI.yml`, `.github/workflows/rust-release.yml`, and `.github/workflows/wheels-release.yml` to the new full release, for example `22.1.0`.
+2. The versioned `llvm-sys` env var name everywhere it appears, for example `LLVM_SYS_211_PREFIX` to `LLVM_SYS_220_PREFIX`.
+3. `Cargo.toml`:
+   - `inkwell` feature, for example `llvm21-1` to `llvm22-1`
+   - `llvm-sys` crate version, for example `211.0.0` to `220.0.0`
+4. `pyproject.toml` and `README.md` for any remaining version-specific install examples, especially `llvm@21` and `LLVM_SYS_*`.
+
+The manylinux images already install to `/opt/llvm`, so they should not need path changes for a version bump.
+
+After the bump, run:
+
+1. `cargo test --lib --all-features`
+2. `cargo run --example rust_api --all-features`
+3. `make lint`
+4. the CI matrix and wheel builds

README.md

@@ -55,12 +55,6 @@ uv pip install qir-qis
 pip install qir-qis
 ```
 
-For development installation:
-
-```sh
-uv sync
-```
-
 ## Usage
 
 ### Command Line
@@ -101,136 +95,6 @@ See [examples/rust_api.rs](https://github.com/quantinuum/qir-qis/blob/main/examp
 cargo run --example rust_api
 ```
 
-## Development
-
-### Setting Up Development Environment
-
-```sh
-# Clone the repository
-git clone https://github.com/quantinuum/qir-qis.git
-cd qir-qis
-
-# Install LLVM 21 (macOS/Homebrew example)
-brew install llvm@21
-export LLVM_SYS_211_PREFIX=/opt/homebrew/opt/llvm@21
-
-# Install Rust dependencies and build
-cargo build
-
-# Install Python dependencies
-uv sync
-```
-
-### Building
-
-```sh
-# Build Rust binary
-LLVM_SYS_211_PREFIX=${LLVM_SYS_211_PREFIX:-/opt/homebrew/opt/llvm@21} \
-cargo build --release
-
-# Build Python package
-LLVM_SYS_211_PREFIX=${LLVM_SYS_211_PREFIX:-/opt/homebrew/opt/llvm@21} \
-uv run maturin build --release
-```
-
-### Testing
-
-#### Running Tests
-
-Tests require [cargo-nextest](https://nexte.st/docs/installation/pre-built-binaries/):
-
-```sh
-# Run all tests
-LLVM_SYS_211_PREFIX=${LLVM_SYS_211_PREFIX:-/opt/homebrew/opt/llvm@21} \
-make test
-
-# Or directly with cargo
-LLVM_SYS_211_PREFIX=${LLVM_SYS_211_PREFIX:-/opt/homebrew/opt/llvm@21} \
-cargo nextest run --all-targets --all-features
-```
-
-#### Testing Individual Files
-
-```sh
-# Compile a single QIR file
-make compile FILE=tests/data/adaptive.ll
-
-# Compile all test files
-make allcompile
-```
-
-#### Simulation Testing with Selene
-
-Test the compiled QIS using [Selene quantum simulator](https://docs.quantinuum.com/selene/):
-
-```sh
-# Simulate a single file (runs 5 shots by default)
-make sim FILE=tests/data/adaptive.ll
-
-# Simulate all test files
-make allsim
-```
-
-This will:
-
-1. Compile the QIR to QIS
-2. Run it on the Selene/Quest simulator
-3. Display measurement results
-
-### Code Quality
-
-```sh
-# Run linters
-make lint
-
-# This runs:
-# - prek (pre-commit checks, https://prek.j178.dev/)
-# - typos checker
-# - cargo clippy
-```
-
-### Regenerating Python Stubs
-
-After modifying the Python API:
-
-```sh
-make stubs
-```
-
-This updates [qir_qis.pyi](https://github.com/quantinuum/qir-qis/blob/main/qir_qis.pyi) with the latest type signatures.
-
-## Project Structure
-
-```text
-qir-qis/
-├── src/
-│   ├── main.rs          # CLI entry point
-│   ├── lib.rs           # Library and Python bindings
-│   ├── convert.rs       # QIR to QIS conversion logic
-│   ├── decompose.rs     # Gate decomposition
-│   ├── opt.rs           # LLVM optimization passes
-│   └── utils.rs         # Helper utilities
-├── tests/
-│   ├── data/            # Test QIR files
-│   └── snaps/           # Snapshot test results
-├── main.py              # Example Python usage with simulation
-├── Cargo.toml           # Rust package configuration
-├── pyproject.toml       # Python package configuration
-└── Makefile             # Common development tasks
-```
-
-## Common Makefile Targets
-
-| Command                    | Description                        |
-|----------------------------|------------------------------------|
-| `make test`                | Run all unit and integration tests |
-| `make compile FILE=<path>` | Compile a single QIR file          |
-| `make sim FILE=<path>`     | Compile and simulate a QIR file    |
-| `make lint`                | Run code quality checks            |
-| `make stubs`               | Regenerate Python type stubs       |
-| `make allcompile`          | Compile all test files             |
-| `make allsim`              | Simulate all test files            |
-
 ## Contributing
 
 Contributions are welcome! Please read [CONTRIBUTING.md](https://github.com/quantinuum/qir-qis/blob/main/CONTRIBUTING.md) for:
@@ -239,11 +103,7 @@ Contributions are welcome! Please read [CONTRIBUTING.md](https://github.com/quan
 - Coding standards and commit message format
 - Development workflow and testing requirements
 
-**Quick checklist before submitting:**
-
-- [ ] Tests pass: `make test`
-- [ ] Linters pass: `make lint`
-- [ ] Documentation updated
+Development setup, test commands, and LLVM upgrade guidance live in [DEVELOPMENT.md](https://github.com/quantinuum/qir-qis/blob/main/DEVELOPMENT.md). Release notes are available in [CHANGELOG.md](https://github.com/quantinuum/qir-qis/blob/main/CHANGELOG.md).
 
 ## License