docs: add maintainer guide

Author: zah

MAINTANERS.md

@@ -0,0 +1,91 @@
+# Maintainer Guide
+
+This document collects notes and commands useful when maintaining
+`codetracer-ruby-recorder`.
+
+## Development environment
+
+This repository provides a Nix flake for the development shell. With
+`direnv` installed, the shell is loaded automatically when you enter the
+repository directory. Run `direnv allow` once to enable it.
+
+The same environment is configured for GitHub Codespaces via the
+provided devcontainer configuration.
+
+## Building the native extension
+
+The tracer ships with a Rust extension located in `ext/native_tracer`.
+To build it locally run:
+
+```bash
+just build-extension
+```
+
+This compiles the extension in release mode using Cargo. The resulting
+shared library is placed under
+`ext/native_tracer/target/release/` and is loaded by `src/native_trace.rb`.
+
+## Running tests and benchmarks
+
+Execute the full test suite with:
+
+```bash
+just test
+```
+
+The tests run several sample programs from `test/programs` and compare
+the generated traces with the fixtures under `test/fixtures`.
+
+Benchmarks can be executed with:
+
+```bash
+just bench
+```
+
+## Publishing gems
+
+Two Ruby gems are published from this repository:
+
+* **codetracer-ruby-recorder** – the tracer with the compiled native
+  extension. Prebuilt gems are produced per target platform using
+  [`rb_sys`](https://github.com/oxidize-rb/rb-sys).
+* **codetracer_pure_ruby_recorder** – a pure Ruby fallback without the
+  native extension.
+
+### Native extension gem
+
+1. Install the development dependencies:
+
+   ```bash
+   bundle install
+   ```
+
+2. For each target platform set `RB_SYS_CARGO_TARGET` and build the gem:
+
+   ```bash
+   RB_SYS_CARGO_TARGET=x86_64-unknown-linux-gnu rake cross_native_gem
+   ```
+
+   Replace the target triple with the desired platform (for example
+   `aarch64-apple-darwin`).
+
+3. Push the generated gem found in `pkg/` to RubyGems:
+
+   ```bash
+   gem push pkg/codetracer-ruby-recorder-<version>-x86_64-linux.gem
+   ```
+
+Repeat these steps for each supported platform.
+
+### Pure Ruby gem
+
+The pure Ruby tracer is packaged from the files under `src/`. Build and
+publish it with:
+
+```bash
+gem build codetracer_pure_ruby_recorder.gemspec
+gem push codetracer_pure_ruby_recorder-<version>.gem
+```
+
+Ensure the version matches the native extension gem so that both
+packages can be used interchangeably.

README.md

@@ -24,14 +24,8 @@ ruby src/native_trace.rb <path to ruby file>
 ```
 
 however you probably want to use it in combination with CodeTracer, which would be released soon.
-
-### Development
-
-This repository provides a Nix flake for the development shell. With direnv installed, the shell is loaded automatically when you enter the directory. Run `direnv allow` once to enable it.
-
-The same environment is configured for GitHub Codespaces via devcontainer configuration.
-
 ### env variables
+For maintainer instructions, see [MAINTANERS.md](MAINTANERS.md).
 
 * if you pass `CODETRACER_RUBY_TRACER_DEBUG=1`, you enables some additional debug-related logging
 * `CODETRACER_DB_TRACE_PATH` can be used to override the path to `trace.json` (it's used internally by codetracer as well)