Developer Guide¶

Last updated: 03/09/2026

Target¶

This guide is designed for developers looking to read, modify, or extend the ray-ascend source code. It provides a comprehensive walkthrough from setting up your development environment to submitting a pull request.

Quick Start Checklist¶

✅ Environment Setup - Install dependencies and set up your development environment
✅ Clone and Build - Get the ray-ascend repository and install it
✅ Understand Code Structure - Familiarize yourself with the project layout
✅ Follow Coding Standards - Write code according to project conventions
✅ Build and Test - Implement features and run tests
✅ Submit Contribution - Sign the CLA and create a pull request

Preparation¶

Before starting development, you need to set up your environment. Refer to Setup Guide for detailed instructions:

Key Steps:¶

Install CANN (Optional): Required only if you have NPU devices and want to use NPU tensor for transmission.
Choose Installation Type:
- Basic Installation: pip install -e .
- With YR Support: pip install -e ".[yr]" (includes YuanRong direct tensor transport)
- Full Installation: pip install -e ".[all]" (all features for development and testing)

See Setup Guide for complete installation instructions.

Clone and Build¶

# Clone the repository
git clone https://github.com/Ascend/ray-ascend.git
cd ray-ascend

# Build from source (editable installation)
pip install -e .

# Or build with all features
pip install -e ".[all]"

Code Structure¶

The ray-ascend project is organized as follows:

ray_ascend/
├── collective/              # HCCL collective communication
└── direct_transport/        # YuanRong direct tensor transport


tests/
├── collective/              # Tests for collective communication
└── direct_transport/        # Tests for tensor transport

Main Components:

collective/: HCCL-based collective communication group implementation
direct_transport/: YuanRong direct tensor transport implementation
tests/: Comprehensive test suite using pytest

Coding Standards and Submission¶

Before committing your code:

Setup pre-commit hooks to automatically check code quality:

pip install pre-commit
pre-commit install
git config user.name "Your Name"
git config user.email "your.email@example.com"

Follow project coding standards - see Contributing Guide for detailed style conventions

Commit with signature:

git commit -s  # -s flag adds sign-off, triggering pre-commit hooks

For complete information on code style, pre-commit setup, and contribution guidelines, refer to Contributing Guide.

Build and Test¶

Run tests using pytest to ensure your changes don't break existing functionality:

# Install all development dependencies
pip install -e ".[all]"

# Run all tests
pytest -v

All tests must pass before submitting a PR. For more testing details and options, see Contributing Guide.

Submit Your Contribution¶

Prerequisites¶

Before submitting a Pull Request, you must:

1. Sign the Ascend CLA (Contributor License Agreement)¶

Required for first-time contributors only

Visit the Ascend CLA Sign Portal.

For details, see Sign the Ascend CLA.

⚠️ Important: The email address used to sign the CLA must match your Git commit email address.

2. Verify Your Setup¶

# Confirm Git configuration
git config user.name
git config user.email

# These should match your CLA signature

Submission Steps¶

Create a Feature Branch

git checkout -b feature/your-feature-name

Make Your Changes
- Write code following all coding standards above
- Add or update tests as necessary
- Update documentation if needed
Test Everything
```
pytest -v
```
All tests must pass.

Commit with Signature

git commit -s -m "Clear and descriptive commit message"

Push and Create PR
```
git push origin feature/your-feature-name
```
Then create a pull request on GitHub.

PR Review Checklist¶

Before submitting, please ensure:

✅ Code follows all style conventions
✅ All tests pass
✅ New features have corresponding tests
✅ Documentation is updated
✅ Commits are signed (-s flag)
✅ CLA is signed (first-time contributors)
✅ Commit email matches CLA email

Documentation¶

Documentation updates should be made to the relevant .md files in the docs/ directory. Use clear, concise language with code examples where appropriate.

Additional Resources¶

Setup Guide - Detailed environment setup instructions
Contributing Guide - Contribution workflow and guidelines

Getting Help¶

If you encounter any issues:

Check the documentation above
Review existing issues and PRs
Open a new issue on GitHub with detailed information