Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
244 lines (179 loc) · 5.64 KB

CONTRIBUTING.md

File metadata and controls

244 lines (179 loc) · 5.64 KB

Contributing to json-as

Thank you for your interest in contributing to json-as! This document provides guidelines and instructions for contributing.

Table of Contents

Getting Started

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/YOUR_USERNAME/json-as.git
cd json-as
  3. Add the upstream remote: 
    git remote add upstream https://github.com/JairusSW/json-as.git

Development Setup

Prerequisites

  • Node.js 18+ or Bun
  • Wasmtime (for running tests)

Install Dependencies

npm install
# or
bun install

Build the Transform

The transform is written in TypeScript and needs to be compiled:

npm run build:transform

Running Tests

Run the full test suite across all modes (NAIVE, SWAR, SIMD):

npm test

Run a specific test file:

npm test string # Runs string.spec.ts

Running Benchmarks

AssemblyScript benchmarks:

npm run bench:as

JavaScript comparison benchmarks:

npm run bench:js

Project Structure

json-as/
├── .as-test/          # As-test configuration and runners
├── assembly/          # AssemblyScript runtime implementation
│   ├── index.ts       # Main entry point (JSON namespace)
│   ├── serialize/     # Serialization implementations
│   │   ├── index/     # Indexer of all methods
│   │   ├── simple/    # Naive implementation
│   │   ├── swar/      # SWAR-optimized
│   │   └── simd/      # SIMD-optimized
│   ├── deserialize/   # Deserialization implementations
│   │   ├── index/     # Indexer of all methods
│   │   ├── simple/    # Naive implementation
│   │   ├── swar/      # SWAR-optimized
│   │   └── simd/      # SIMD-optimized
│   ├── util/          # Utility functions
│   ├── custom/        # Constants and character codes
│   └── __tests__/     # Test files
├── transform/         # TypeScript compiler transform
│   └── src/           # Transform source code
├── lib/               # Shared utilities (buffer system)
├── bench/             # Benchmark suite
└── .github/           # CI/CD workflows

Making Changes

Branching Strategy

  1. Create a feature branch from main:

    git checkout -b feature/your-feature-name

  2. Make your changes with clear, atomic commits

  3. Keep your branch up to date:

    git fetch upstream
git rebase upstream/main

Commit Messages

Use clear, descriptive commit messages:

  • feat: add support for BigInt serialization
  • fix: handle escaped unicode in strings
  • perf: optimize SIMD string escaping
  • docs: update README examples
  • test: add edge case tests for nested arrays
  • chore: update dependencies

Testing

Writing Tests

Tests are located in assembly/__tests__/. Each test file follows the pattern *.spec.ts.

Example test structure:

import { JSON } from "..";

describe("Feature Name", () => {
  test("should serialize correctly", () => {
    const result = JSON.stringify<string>("hello");
    expect(result).toBe('"hello"');
  });

  test("should deserialize correctly", () => {
    const result = JSON.parse<string>('"hello"');
    expect(result).toBe("hello");
  });
});

Test Coverage

Ensure your changes include tests for:

  • Happy path scenarios
  • Edge cases
  • Error conditions
  • All three modes (NAIVE, SWAR, SIMD) if applicable

Code Style

Formatting

The project uses Prettier for formatting:

npm run format

AssemblyScript Guidelines

  • Use @inline decorator for small, frequently-called functions
  • Prefer store<T> and load<T> for direct memory operations
  • Use typed arrays and explicit types
  • Add // @ts-ignore comments with explanations when necessary

TypeScript Guidelines (Transform)

  • Use strict TypeScript settings
  • Document complex logic with comments
  • Keep functions focused and small

Pull Request Process

  1. Before submitting:

    • Run the full test suite: npm test
    • Run the formatter: npm run format
    • Ensure your branch is up to date with main

  2. PR Description:

    • Clearly describe the changes
    • Reference any related issues
    • Include before/after benchmarks for performance changes

  3. Review Process:

    • PRs require at least one approval
    • Address review feedback promptly
    • Keep the PR focused on a single concern

  4. After Merge:

    • Delete your feature branch
    • Update any related issues

Reporting Issues

Bug Reports

Include:

  • json-as version
  • AssemblyScript version
  • Minimal reproduction case
  • Expected vs actual behavior
  • Error messages (if any)

Feature Requests

Include:

  • Use case description
  • Proposed API (if applicable)
  • Alternatives considered

Performance Contributions

If your change affects performance:

  1. Run benchmarks before and after
  2. Include benchmark results in the PR
  3. Test across all three modes (NAIVE, SWAR, SIMD)
  4. Consider memory usage implications

Questions?

License

By contributing, you agree that your contributions will be licensed under the MIT License.