Contributing to ASON

November 11, 2025 · View on GitHub

Thank you for your interest in contributing to ASON! This document provides guidelines and instructions for contributing to this project.

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:

Use a clear and descriptive title
Describe the exact steps to reproduce the problem
Provide specific examples including JSON inputs and expected vs actual outputs
Describe the behavior you observed and explain what behavior you expected
Include screenshots or code snippets if relevant
Specify your environment: Node.js version, OS, etc.

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:

Use a clear and descriptive title
Provide a detailed description of the suggested enhancement
Explain why this enhancement would be useful to most ASON users
List examples of how the feature would be used
Mention if you're willing to implement the enhancement yourself

Pull Requests

Fork the repository and create your branch from main
Make your changes following our coding standards (see below)
Add tests if you're adding functionality
Ensure all tests pass: npm test in nodejs-compressor/
Update documentation if you're changing functionality
Write a clear commit message describing your changes
Submit a pull request with a comprehensive description

Development Setup

Node.js Implementation

# Clone the repository
git clone https://github.com/ason-format/ason.git
cd ason

# Install dependencies for Node.js version
cd nodejs-compressor
npm install

# Run tests
npm test

# Run benchmarks
node benchmarks/toon-comparison-benchmark.js

Web Visualizer

# Navigate to docs directory
cd docs

# Start a local server
python3 -m http.server 8000

# Open http://localhost:8000 in your browser

Coding Standards

JavaScript Style Guide

Use ES6+ features where appropriate
Follow consistent indentation (2 spaces)
Use meaningful variable names
Add JSDoc comments for public APIs
Keep functions small and focused
Prefer const over let, avoid var

Example:

/**
 * Compresses a JSON object to ASON format
 * @param {Object} data - The JSON data to compress
 * @param {Object} options - Compression options
 * @returns {string} The compressed ASON string
 */
compress(data, options = {}) {
  // Implementation
}

Testing

Write tests for new features and bug fixes
Maintain or improve test coverage
Use descriptive test names that explain what is being tested
Follow the existing test structure in the codebase

Example test:

test('compresses uniform array with references', () => {
  const input = {
    users: [
      { id: 1, name: 'Alice' },
      { id: 2, name: 'Bob' }
    ]
  };
  const result = compressor.compress(input);
  expect(result).toContain('@id,name');
});

Commit Messages

Use the present tense ("Add feature" not "Added feature")
Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
Limit the first line to 72 characters or less
Reference issues and pull requests when relevant

Examples:

Add inline-first dictionary compression
Fix decompression of nested arrays
Update benchmarks with new test data

Project Structure

nodejs-compressor/
├── src/
│   └── compressor/
│       ├── SmartCompressor.js  # Main compression engine
│       └── PatternDetector.js  # Pattern detection logic
├── tests/
│   └── compressor.test.js      # Test suite
├── benchmarks/                  # Performance benchmarks
└── examples/                    # Sample data files

docs/
├── index.html                   # Web visualizer
├── docs.html                    # Documentation page
├── benchmarks.html              # Benchmarks page
├── js/
│   ├── compressor.js           # Browser-compatible compressor
│   ├── app.js                  # Visualizer logic
│   └── benchmarks.js           # Benchmark runner
└── css/
    └── styles.css              # Styles