> ## Documentation Index
> Fetch the complete documentation index at: https://zinc.ossl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to build, test, and contribute to Zinc

Zinc is an open-source project. Contributions are welcome at every level: bug reports, documentation improvements, new language adapters, and platform backends.

## Repository structure

```
zinc/
├── core/              # Rust core library (the heart of everything)
├── include/           # Generated C header (zinc.h)
├── adapters/          # Language-specific wrappers
│   ├── python/
│   ├── go/
│   ├── node/
│   ├── bun/
│   ├── deno/
│   ├── cpp/
│   ├── java/
│   └── csharp/
├── docs/              # Mintlify documentation
├── examples/          # Multi-language examples
└── benches/           # Criterion benchmarks
```

## Building the core

```bash theme={null}
git clone https://github.com/ossl-dev/zinc
cd zinc
cargo build --release --manifest-path core/Cargo.toml
```

This produces `core/target/release/libzinc_core.{so,dylib}` and generates `include/zinc.h`.

## Running tests

```bash theme={null}
# Rust core tests
cargo test --manifest-path core/Cargo.toml

# With specific test
cargo test --manifest-path core/Cargo.toml -- create_open_write_read

# All tests including doc tests
cargo test --manifest-path core/Cargo.toml --all-features
```

**Python adapter tests:**

```bash theme={null}
cd adapters/python
pip install -e .
python -m pytest
```

**Node adapter tests:**

```bash theme={null}
cd adapters/node
npm install
npm test
```

**Go adapter tests:**

```bash theme={null}
cd adapters/go
CGO_LDFLAGS="-L../../core/target/release" go test
```

## Linting

```bash theme={null}
cargo clippy --manifest-path core/Cargo.toml -- -D warnings
```

No `unwrap()` calls are allowed in core library code. The CI build enforces this. Use `?` for error propagation and `.expect("reason")` for infallible operations with a documented justification.

## Adding a new language adapter

Every adapter follows the same pattern:

1. Load `libzinc_core.{so,dylib}` via the language's FFI mechanism.
2. Read `include/zinc.h` (or replicate the function signatures) to define FFI bindings.
3. Wrap the C functions in a language-native `SharedRegion` class or module.
4. Provide `create`, `open`, data access, `notify`, `wait`, and `close` methods.
5. Implement zero-copy data access (return a native buffer/view/slice backed by the mmap).

New adapters belong in `adapters/<language>/`. Each adapter should have:

* A build file (`Cargo.toml`, `pyproject.toml`, `go.mod`, `package.json`, etc.)
* A README with installation and usage instructions
* A test file that exercises the full API surface against a running core library

The test pattern for a new adapter:

1. Build the core library (`cargo build --release`).
2. Load the adapter and call `create` with a test name and capacity.
3. Write a known pattern to the data area.
4. Call `open` in a separate process or thread.
5. Verify the data is identical (no corruption, no copy).
6. Test notify/wait roundtrip.
7. Close both handles and verify the region is unlinked.

## Adding a platform backend

Platform backends live in `core/src/platform/`. Each backend implements three functions:

* `map(name, mode) -> MappedFile` -- creates or opens a shared memory segment and maps it.
* `unmap(file) -> Result<()>` -- unmaps the segment.
* `unlink(name) -> Result<()>` -- removes the segment name from the system.

The `sync.rs` module handles notify/wait and is platform-specific. The Linux backend uses `futex`. Other platforms should implement the same semantics: an atomic increment for `notify` and a blocking wait for `wait`.

## Code review

All changes go through pull requests. The review focuses on:

* Correctness of the ownership model (does the new code handle create/open/close/unlink correctly?)
* Platform portability (does the new code compile on Linux and macOS?)
* Performance (does the hot path avoid allocation and system calls?)
* Error handling (are all error paths covered, and do they map to appropriate `ZincError` values?)

## Release process

Releases follow semantic versioning with a single version across all packages. The release checklist:

1. Update version numbers in `core/Cargo.toml` and all adapter package files.
2. Run the full test suite on Linux and macOS.
3. Build the core in release mode for all platforms.
4. Run the integration test suite (all adapters against the release build).
5. Tag the release (`git tag v<major>.<minor>.<patch>`).
6. Publish adapter packages to their respective registries.

Each release publishes the core shared library, the C++ header, and adapter packages for all supported languages.

## Questions

Open an issue on GitHub for questions, bug reports, and feature requests. Pull requests should reference the relevant issue.