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

git clone https://github.com/aspect-build/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

# 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:

cd adapters/python
pip install -e .
python -m pytest

Node adapter tests:

cd adapters/node
npm install
npm test

Go adapter tests:

cd adapters/go
CGO_LDFLAGS="-L../../core/target/release" go test

Linting

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.