# Contributing to WasmHub
Thank you for your interest in contributing! This project aims to be community-driven.
## 📁 Project Structure
```sh
wasmhub/
├── src/
│ ├── lib.rs # 📦 Library code
│ └── bin/
│ └── wasmhub.rs # 🔧 CLI binary (feature-gated)
│
├── runtimes/ # 📁 Runtime sources and manifests
│ └── go/
│ ├── main.go # Source file
│ ├── manifest.json # Version metadata
│ └── *.wasm # Built binaries (gitignored)
│
├── scripts/ # 🔧 Build scripts
│ ├── build-all.sh # Build all runtimes
│ ├── build-go.sh # Build Go runtime
│ ├── build-rust.sh # Build Rust runtime
│ ├── generate-metadata.sh # Generate manifest.json
│ └── verify-binary.sh # Verify WASM binary
│
├── .github/workflows/
│ ├── ci.yml # ✅ CI pipeline (tests, lint, format)
│ └── release.yml # 📦 Release workflow (builds WASM + CLI)
│
├── Cargo.toml # 📦 Package manifest
├── Dockerfile # 🐳 Build environment for WASM
├── justfile # 🛠️ Build commands
├── README.md # 📖 User-facing docs
├── CONTRIBUTING.md # 👥 This file
├── LICENSE # ⚖️ MIT License
└── .gitignore # 🚫 Git ignore rules
```
The project is a single Rust crate with:
- **Library API** (`src/lib.rs`) - Can be used programmatically
- **CLI tool** (`src/bin/wasmhub.rs`) - Enabled with `--features cli`
## 🚀 Ways to Contribute
1. **Report Bugs** - Open an issue with reproduction steps
2. **Request Features** - Suggest new runtimes or improvements
3. **Submit PRs** - Fix bugs, add runtimes, improve docs
4. **Improve Documentation** - Help others understand the project
5. **Share** - Star the repo, tell others about it
## 🔧 Development Setup
### Prerequisites
- Rust 1.85+ (`rustup install stable`)
- Git
- Just (optional, for convenient build commands: `cargo install just`)
### Clone & Build
```sh
# Clone repository
git clone https://github.com/anistark/wasmhub.git
cd wasmhub
# Build library only
cargo build
# Build library + CLI
cargo build --features cli
# Run tests
cargo test
# Run CLI locally
cargo run --features cli -- --help
# Install CLI globally
cargo install --path . --features cli
```
## 📝 Code Style
```sh
# Format code
just format
# Lint code
just lint
# Auto-fix linting issues
just lint-fix
```
All PRs must pass formatting and linting checks.
## 🧪 Testing
Write tests for all new features:
```rust
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_language_from_str() {
assert_eq!(Language::from_str("nodejs"), Some(Language::NodeJs));
assert_eq!(Language::from_str("unknown"), None);
}
}
```
Run tests:
```sh
cargo test
```
## 📦 Adding a New Runtime
WASM binaries are **not** committed to the repository. They are built by CI and published as GitHub Release assets.
### Steps to Add a New Runtime
1. **Create the source directory**: `runtimes/<language>/`
2. **Add the source file** (e.g., `main.go`, `lib.rs`)
3. **Create a build script**: `scripts/build-<language>.sh`
4. **Update `scripts/build-all.sh`** to include your language
5. **Add to `Language` enum** in `src/runtime.rs`
6. **Write tests**
7. **Update README.md** with the new runtime
8. **Submit PR**
Example for adding Java:
```sh
# Create runtime directory with source
mkdir -p runtimes/java
# Add source file (e.g., Main.java)
# Create build script
cat > scripts/build-java.sh << 'EOF'
#!/usr/bin/env bash
# Build Java to WASM using TeaVM or similar
EOF
chmod +x scripts/build-java.sh
# Update build-all.sh to include Java builds
# Update Language enum in src/runtime.rs
git commit -am "Add Java runtime support"
```
### Runtime Directory Structure
```sh
runtimes/
├── go/
│ ├── main.go # Source file (committed)
│ ├── manifest.json # Generated by build (committed)
│ └── go-1.23.wasm # Built binary (gitignored, in releases)
└── rust/
├── Cargo.toml # Source (committed)
├── src/lib.rs # Source (committed)
├── manifest.json # Generated by build (committed)
└── rust-1.75.wasm # Built binary (gitignored, in releases)
```
### Manifest Format
Each runtime has a `manifest.json` that describes available versions:
```json
{
"language": "go",
"latest": "1.23",
"versions": {
"1.23": {
"file": "go-1.23.wasm",
"size": 266712,
"sha256": "efa1e13f39dfd3783d0eff5669088ab99a1ea1d38ac79f29b02e2ad8ddfea29d",
"released": "2026-02-03T13:23:13Z",
"wasi": "wasip1",
"features": []
}
}
}
```
The manifest is auto-generated by `scripts/generate-metadata.sh` during the build process.
## 🔄 CI/CD and Releases
### Continuous Integration
Every PR and push to `main` triggers CI checks:
- **Test**: Runs `cargo test` on Linux, macOS, and Windows
- **Format**: Checks code formatting with `cargo fmt`
- **Lint**: Runs `cargo clippy` for linting
### Release Process
When a GitHub Release is created:
1. **WASM runtimes are built** using the Docker build environment
2. **Manifests are generated** with checksums and metadata
3. **Binaries are uploaded** as release assets
4. **CLI binaries** are cross-compiled for all platforms
To create a release:
```sh
# Update version in Cargo.toml, then run:
just publish
# Or for GitHub release only (no crates.io):
just publish-github
# Or with explicit version:
just release 0.2.0
```
### Build Environment
WASM runtimes are built in a Docker container with:
- WASI SDK (for C/C++ compilation)
- TinyGo (for Go compilation)
- Rust with `wasm32-wasip1` target
- `wasm-opt` for binary optimization
To build locally:
```sh
# Using Docker (recommended)
just docker-build # Build the Docker image
just docker-build-runtimes # Build all WASM runtimes
# Or install dependencies natively and run
./scripts/build-all.sh
```
---
## 🐛 Reporting Bugs
Open an issue with:
- **Description** - What went wrong?
- **Steps to reproduce**
- **Expected behavior**
- **Actual behavior**
- **Environment** - OS, Rust version, etc.
## 💡 Feature Requests
Open an issue with:
- **Use case** - Why is this needed?
- **Proposed solution**
- **Alternatives considered**
## 🔀 Pull Request Process
1. **Fork** the repository
2. **Create a branch** - `git checkout -b feature/my-feature`
3. **Make changes** - Follow code style
4. **Write tests** - Ensure coverage
5. **Update docs** - If needed
6. **Commit** - Use clear commit messages
7. **Push** - `git push origin feature/my-feature`
8. **Open PR** - Fill out the template
### PR Checklist
- [ ] Code follows Rust style guide (`cargo fmt`)
- [ ] No clippy warnings (`cargo clippy`)
- [ ] Tests added and passing (`cargo test`)
- [ ] Documentation updated
- [ ] CHANGELOG.md updated (if applicable)
## 📜 Commit Messages
Use conventional commits:
```
feat: add Java runtime support
fix: correct cache path on Windows
docs: update CLI usage examples
test: add integration tests for loader
chore: update dependencies
```
## 🏷️ Issue Labels
- `good-first-issue` - Great for newcomers
- `help-wanted` - Need community help
- `bug` - Something isn't working
- `enhancement` - New feature request
- `documentation` - Docs improvements
## ⚖️ Code of Conduct
Be respectful, inclusive, and collaborative. We're building this together.
## 📞 Questions?
- Open a [Discussion](https://github.com/anistark/wasmhub/discussions)
- Ask on Discord (coming soon)
- Email: ani@anistark.com
## 💡 Quick Reference
### Common Commands
Using justfile (recommended):
```sh
# Show all available commands
just --list
# Format code
just format
# Lint code
just lint
# Auto-fix lint issues
just lint-fix
# Check compilation
just check
# Build library
just build
# Build with all features
just build-all
# Run tests
just test
# Run all CI checks locally
just ci
# Install CLI globally
just install
```
Or using cargo directly:
```sh
# Build everything (library + CLI)
cargo build --all-features
# Run all tests
cargo test
# Format code
cargo fmt --all
# Lint code
cargo clippy --all-features
# Run CLI locally
cargo run --features cli -- list
# Check documentation
cargo doc --open
# Build release binary
cargo build --release --features cli
```
### Project Layout
- **src/lib.rs** - Public API for the library
- **src/bin/wasmhub.rs** - CLI application code
- **runtimes/** - Downloaded WASM runtime binaries
- **Cargo.toml** - Package manifest with `cli` feature flag
### Feature Flags
- **default** - Library only, no CLI
- **cli** - Includes CLI binary with `clap` argument parsing
Thank you for contributing! 🎉