Contributing guidelines

​

Workflow compliance

​

Required reading

​

Key requirements

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

# TypeScript
cd ts
pnpm run build
pnpm run test

​

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

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

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

# TypeScript tests
cd ts
pnpm run test

​

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

• 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

​

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

• 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

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

• 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

# 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

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

​

Documentation

​

Updating documentation

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

​

Python 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

/**
 * 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

​

Contact maintainers

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

​

License

​

Next steps