Contributing guidelines

Learn how to contribute to the WAX project

We welcome contributions to WAX! This guide will help you get started.

Workflow compliance

All contributions must follow the established workflow rules from the hive/hive repository.

Required reading

General workflow

Claude-specific workflow rules

Git guidelines

Branching and merge requests

Contributing guide

Bug reports and enhancements

Key requirements

1. Create draft merge requests

   Always create MRs as Draft until maintainer approval.

2. Build and test locally

   Build and test locally before pushing changes.

   # Python
   ./python/wax/scripts/build_wax.sh
   ./python/tests/wax/run_tests.sh
   
   # TypeScript
   cd ts
   pnpm run build
   pnpm run test
   
3. Monitor pipeline

   Monitor pipeline after push and fix failures promptly.

4. Keep commits atomic

   Keep commits atomic. Use fixup commits for review feedback.

5. Rebase before merge

   Follow fast-forward merge strategy - rebase before merge.

All CI jobs must pass. Marking jobs as allow_failure is not permitted.

Development setup

Prerequisites

• Git: Version control
• Python 3.12+: For Python development
• Node.js 20.11+: For TypeScript development
• Poetry 2.1.3: Python dependency management
• pnpm: TypeScript package manager
• Protobuf compiler: For protocol buffer generation

Clone the repository

git clone https://gitlab.syncad.com/hive/wax.git
cd wax

# Initialize submodules
git submodule update --init --recursive

Set up Python development

# Install Poetry
curl -sSL https://install.python-poetry.org | python3 - --version 2.1.3

# Create virtual environment
cd python/wax
poetry env use python3.12

# Install dependencies
poetry install

# Build WAX
../../python/wax/scripts/build_wax.sh

Set up TypeScript development

# Install pnpm (if not already installed)
npm install -g pnpm

# Install dependencies
cd ts
pnpm install

# Build WAX
pnpm run build

Making changes

Branching strategy

Create a feature branch from develop:

git checkout develop
git pull
git checkout -b feature/your-feature-name

Code style

Python

• Follow PEP 8 style guidelines
• Use Ruff for linting
• Use MyPy for type checking
• Maximum line length: 120 characters

# Run linters
poetry run ruff check .
poetry run mypy .

# Auto-fix issues
poetry run ruff check --fix .

TypeScript

• Follow project ESLint configuration
• Use TypeScript strict mode
• Document public APIs with JSDoc comments

# Run linter
pnpm run lint

Running tests

Always run tests before committing:

# Python tests
./python/tests/wax/run_tests.sh

# TypeScript tests
cd ts
pnpm run test

Commit messages

Write clear, descriptive commit messages:

feat: add support for custom API endpoints

Implement extend() method for HiveChain to allow custom
API endpoint registration. Includes tests and documentation.

Closes #123

Commit message format:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• test: Test additions or changes
• refactor: Code refactoring
• perf: Performance improvements
• chore: Build process or auxiliary tool changes

Submitting changes

Create a merge request

1. Push your branch to GitLab:

   git push origin feature/your-feature-name
   

2. Create a merge request on GitLab

3. Mark it as Draft initially

4. Fill in the MR template with:

   • Description of changes
   • Testing performed
   • Related issues

MR checklist

1. All tests pass locally

   Run full test suite and verify all tests pass.

2. Linters pass

   Run linters and fix all issues.

3. Documentation updated

   Update documentation for any API changes.

4. Examples work

   If applicable, update examples to demonstrate new features.

5. CI pipeline passes

   Monitor the CI pipeline and fix any failures.

Review process

1. Wait for maintainer review
2. Address review feedback
3. Use fixup commits for review changes:
   git commit --fixup HEAD
   
4. Once approved, maintainer will remove Draft status
5. Rebase and squash before merge:
   git rebase -i develop
   git push --force-with-lease
   

Development guidelines

Architecture

Understand the codebase structure:

• core/: Common C++ code shared by Python and TypeScript

  • Tightly integrated with hive submodule
  • Uses libraries/protocol and libraries/fc
  • Avoid deep scanning during analysis

• python/: Python implementation

  • Cython bindings in wax/cpp_python_bridge.pyx
  • Public API in wax/__init__.py
  • Internal implementation in wax/_private/

• ts/: TypeScript implementation

  • WASM compilation from C++
  • Minimize final NPM package size
  • Core in wasm/lib/detailed/

Protocol buffers

Protocol buffers are generated from hive/libraries/protocol/proto/:

• TypeScript: Generated to ts/wasm/lib/proto/ via ts-proto
• Python: Generated to python/wax/_private/proto/ via grpcio-tools

Pattern files track expected output:

• ts/protobuf_patterns/: TypeScript patterns
• python/protobuf_patterns/: Python patterns

Testing guidelines

Write tests for new features

• Add unit tests for new functions/methods
• Add integration tests for complex features
• Ensure tests are deterministic

Use the mock server

For API-related tests, use the provided mock server:

# Python
@pytest.fixture
def hive_chain(proxy_mock_server_endpoint):
    return create_hive_chain(proxy_mock_server_endpoint)

// TypeScript
const chain = await createHiveChain(mockServerEndpoint);

Test coverage

Aim for high test coverage:

• Unit tests for core functionality
• Integration tests for API calls
• End-to-end tests for complete workflows

Documentation

Updating documentation

When adding new features:

1. Update API reference documentation
2. Add usage examples
3. Update guides if applicable
4. Add changelog entry

Python docstrings

Use Google-style docstrings:

def create_transaction(operations: list) -> Transaction:
    """Create a new transaction with the given operations.
    
    Args:
        operations: List of operations to include in the transaction.
        
    Returns:
        A new Transaction object.
        
    Raises:
        ValueError: If operations list is empty.
    """

TypeScript JSDoc

Document public APIs:

/**
 * Create a new transaction with the given operations.
 * 
 * @param operations - List of operations to include
 * @returns A new Transaction object
 * @throws {Error} If operations list is empty
 */
function createTransaction(operations: Operation[]): Transaction {
  // ...
}

Common contribution types

Adding a new operation

1. Define operation in protocol buffers (if not already defined)
2. Implement in both Python and TypeScript
3. Add tests for the operation
4. Add example usage
5. Update documentation

Adding a new API endpoint

1. Extend the API interface
2. Implement the endpoint call
3. Add response type definitions
4. Add tests
5. Document the new endpoint

Fixing a bug

1. Write a failing test that reproduces the bug
2. Fix the bug
3. Verify the test passes
4. Add regression test
5. Document the fix in changelog

Getting help

GitLab issues

Report bugs or request features

Discussions

Ask questions and discuss ideas

Contact maintainers

For questions about contributing:

• Open a discussion on GitLab
• Comment on related issues
• Tag maintainers in merge requests

License

By contributing to WAX, you agree that your contributions will be licensed under the project’s license. See LICENSE.md for details.

Next steps

Building from source

Learn how to build WAX

Running tests

Run tests and examples