Move maintainer docs

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

@@ -25,12 +25,6 @@ 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
 
 * if you pass `CODETRACER_RUBY_TRACER_DEBUG=1`, you enables some additional debug-related logging
@@ -78,6 +72,8 @@ We'd be very happy if the community finds this useful, and if anyone wants to:
 * Provide feedback and discuss alternative implementation ideas: in the issue tracker, or in our [discord](https://discord.gg/qSDCAFMP).
 * Provide [sponsorship](https://opencollective.com/codetracer), so we can hire dedicated full-time maintainers for this project.
 
+For maintainer instructions, see [MAINTANERS.md](MAINTANERS.md).
+
 ### Legal info
 
 LICENSE: MIT