Contributing a Package to the Raiku Community Index

Raiku is a fully community-driven package ecosystem — every package in the index was contributed by someone following the workflow on this page. Contributing means forking the repository, scaffolding your package under UserSub/<Language>/, passing all automated checks, and opening a pull request with a correctly formatted title. The process is designed to be straightforward: the CLI tools handle schema validation, hash computation, and index verification so you can focus on writing great packages.

Before You Start

Read the Rules

Read rules.md in full before writing a single line. CI and reviewers enforce every rule strictly — packages that violate them are rejected.

Install the CLI

Clone the repo and install the CLI locally so you can run raiku validate and raiku publish:

git clone https://github.com/SGizek/Raiku
cd Raiku
pip install -e .
raiku --version

Sync the Index

Sync the latest package index so the validator can resolve dependency names during raiku validate:

raiku sync

Full PR Workflow

Fork the repository

Fork the Raiku repository on GitHub and clone your fork locally:

# Fork at: https://github.com/SGizek/Raiku
git clone https://github.com/<your-username>/Raiku
cd Raiku

Create a branch for your package following the required naming convention:

git checkout -b add/<language>/your-package-name
# Example: git checkout -b add/rust/blazing-vec

Create your package

Use raiku init to scaffold the package inside the correct language directory, or create the files manually.With the init wizard (recommended):

raiku init your-package-name --language Python
# Then move the generated directory to the right location:
mv your-package-name UserSub/Python/your-package-name

Directly in the UserSub tree:

raiku init --output-dir UserSub/Rust --language Rust blazing-vec

The resulting structure must be:

UserSub/<Language>/your-package-name/
  raiku.toml
  version.yml
  README.md
  src/
    <source files>

Replace <Language> with one of: Python, Rust, C, CPP, Zig, Java, CSharp, Go.

Write your source code

Fill in src/ with your actual implementation. Replace any placeholder content generated by raiku init. Ensure the code builds correctly using the build_command you declared in raiku.toml.Your README.md must contain at minimum:

What the package does (one to two sentences)
The raiku install <name> install command
A basic usage example

Validate — zero errors required

Run the validator against your package directory. Every check must pass before you proceed:

raiku validate --dir UserSub/<Language>/your-package-name

A successful run prints a green PASSED panel. If errors appear, fix them all before continuing. Common issues are listed in the Troubleshooting section below.

Generate the index entry and SHA-256

raiku publish validates your package one final time, computes the SHA-256 hash of raiku.toml, and prints the exact JSON object to add to index/index.json:

raiku publish --dir UserSub/<Language>/your-package-name

Copy the printed JSON block — you will need it in the next step.

Add the index entry to index/index.json

Open index/index.json and paste your index entry into the "packages" array. The file must remain valid JSON at all times — invalid JSON blocks all installs for every Raiku user.Example entry:

{
    "name": "blazing-vec",
    "version": "1.0.0",
    "language": "Rust",
    "author": "Graydon Hoare",
    "description": "Zero-cost SIMD vector operations for Rust.",
    "path": "UserSub/Rust/blazing-vec",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Verify the index is consistent

Confirm every entry in index/index.json resolves to a valid path and hash — including your new entry:

raiku index --check --root .

All entries must be reported as valid before you push.

Open a pull request

Push your branch and open a PR against the main branch of the upstream repository:

Title: add(<Language>): your-package-name v1.0.0
Branch: add/<language>/your-package-name
Body: include a brief description of the package, the output of raiku validate, and the language or toolchain requirements (e.g. compiler version, runtime)

Example PR title: add(Rust): blazing-vec v1.0.0

PR Requirements

Title Format

PR titles must follow this exact pattern:

add(<Language>): package-name v<version>

Examples:

add(Rust): blazing-vec v1.0.0
add(Python): fast-math v2.1.0
add(Go): goqueue v1.0.0

Branch Name Format

add/<language>/package-name

Examples:

add/rust/blazing-vec
add/python/fast-math
add/go/goqueue

Required PR Body Content

Brief description of what the package does
Output of raiku validate --dir UserSub/<Language>/your-package
Language and build requirements (compiler/runtime version, any external toolchain dependencies)

All CI checks must pass before a PR can be merged. A PR that fails any CI step will not be reviewed until the issues are resolved.

Updating an Existing Package

Bump the version in both files

Increment version in both raiku.toml and version.yml. The two values must match exactly, and the new version must be strictly higher than the currently published version. Follow semantic versioning: PATCH for bug fixes, MINOR for new backward-compatible features, MAJOR for breaking changes.

Add a changelog entry

Add a new entry to the changelog list in version.yml describing what changed. Do not remove old entries.

changelog:
  - "Initial release"
  - "Added vectorised dot product helper"
  - "Fixed precision issue in normalise() for near-zero vectors"

Re-run raiku publish

Run raiku publish to compute the updated SHA-256 for the new raiku.toml:

raiku publish --dir UserSub/<Language>/package-name

Update index/index.json

Update the version and sha256 fields for your package in index/index.json with the values printed by raiku publish.

Open an update PR

Push your changes and open a PR with the update title format:

update(<Language>): package-name v<new-version>

Example: update(Rust): blazing-vec v1.1.0

CI Checks

Every pull request automatically triggers the following checks. Your PR will not be merged until all of them pass:

Full Package Validation

raiku validate --all --strict runs against every package in the entire UserSub/ tree — not just yours. Any pre-existing package your changes accidentally break will fail CI.

JSON Lint

index/index.json is linted for valid JSON syntax. A single misplaced comma or missing bracket fails this check and blocks all user installs.

Schema Check

Every entry in index/index.json is validated against schemas/schema.yml. Entries with missing required fields or invalid types are rejected.

Hash Verification

raiku index --check verifies that every sha256 in the index matches the actual raiku.toml file at the referenced path. Stale or incorrect hashes fail this check.

Verification Suite

python _verify.py runs 60 automated checks covering the CLI, validator, installer, index manager, and parser. All 60 must pass.

Smoke Tests

python _smoke_new.py runs 18 feature smoke tests against live package operations to catch regressions introduced by new packages.

Review Process

Maintainers review contributions for correctness, security, and compliance with rules.md. Specifically, reviewers check that:

The build command is safe and does not contain any forbidden patterns.
The source code does not contain suspicious, offensive, or harmful content.
The package name is unique and follows all naming rules.
All required files are present and well-formed.
The index entry is correctly formatted with an accurate SHA-256 hash.

Reviews typically complete within 3–5 business days. Once a PR is merged, the package is live immediately after the next raiku sync on any user’s machine.

Packages with dangerous build commands, suspicious code, missing fields, or rule violations are rejected — not asked to revise. Start fresh, fix all issues locally, and open a new PR when everything passes raiku validate.

Local Testing Before Opening a PR

Run these commands in the repository root before pushing to ensure everything is in order:

# Validate your specific package
raiku validate --dir UserSub/<Language>/my-package

# Install locally to test the actual build
raiku install ./UserSub/<Language>/my-package

# Validate the entire repository (mirrors CI)
raiku validate --all --strict

# Run the full verification suite (60 checks)
python _verify.py

# Run the feature smoke tests (18 checks)
python _smoke_new.py

# Rebuild the index from scratch and verify it
raiku index --rebuild --dry-run
raiku index --check --root .

Common Contribution Issues

raiku validate reports: version mismatch between raiku.toml and version.yml

The version field must be identical in both files. Open both files and make sure they match exactly — including pre-release suffixes. For example, 1.0.0-beta.1 in raiku.toml requires exactly 1.0.0-beta.1 (not 1.0.0) in version.yml.

raiku validate reports: language does not match directory

The language field in raiku.toml must match the language subdirectory your package lives in. A Rust package placed under UserSub/Python/ will fail this check. Move the package to the correct directory or update the language field.

raiku validate reports: forbidden pattern in build_command

Your build_command contains a pattern that is blocked for security reasons. Review the full list of forbidden patterns in rules.md §7.1 and rewrite the command to achieve the same result without using any of them.

raiku validate reports: src/ directory is empty

The src/ directory must contain at least one file. Add your source code before running validation. If you used raiku init, make sure you replaced the placeholder files with actual content.

CI fails: hash verification — sha256 mismatch

The SHA-256 in index/index.json does not match the actual raiku.toml file. Re-run raiku publish --dir UserSub/<Language>/your-package and replace the sha256 value in your index entry with the freshly computed hash. This typically happens when you edit raiku.toml after running raiku publish.

CI fails: JSON lint on index/index.json

index/index.json contains invalid JSON. Common causes are a trailing comma after the last entry in the array, missing quotes around a string value, or a mismatched bracket. Use a JSON validator locally (python -m json.tool index/index.json) to find and fix the syntax error.

My PR was rejected — what now?

Read the rejection comment carefully. Address every issue raised, re-run the full local test suite, and open a new PR. Do not push fixes to a closed PR. If you are unsure why a PR was rejected, open a GitHub issue at https://github.com/SGizek/Raiku/issues with the question label.

Get Started

Using Packages

Creating Packages

Security

Contributing a Package to the Raiku Community Index

Before You Start

Read the Rules

Install the CLI

Sync the Index

Full PR Workflow

PR Requirements

Title Format

Branch Name Format

Required PR Body Content

Updating an Existing Package

CI Checks

Full Package Validation

JSON Lint

Schema Check

Hash Verification

Verification Suite

Smoke Tests

Review Process

Local Testing Before Opening a PR

Common Contribution Issues

Build docs developers (and LLMs) love

Get Started

Using Packages

Creating Packages

Security

Documentation Index

​Before You Start

Read the Rules

Install the CLI

Sync the Index

​Full PR Workflow

​PR Requirements

​Title Format

​Branch Name Format

​Required PR Body Content

​Updating an Existing Package

​CI Checks

Full Package Validation

JSON Lint

Schema Check

Hash Verification

Verification Suite

Smoke Tests

​Review Process

​Local Testing Before Opening a PR

​Common Contribution Issues

Build docs developers (and LLMs) love

Before You Start

Full PR Workflow

PR Requirements

Title Format

Branch Name Format

Required PR Body Content

Updating an Existing Package

CI Checks

Review Process

Local Testing Before Opening a PR

Common Contribution Issues