TheRock/rocm-libraries/projects/hipdnn/CONTRIBUTING.md

Contributing to hipDNN

Thank you for your interest in contributing to hipDNN!

We welcome contributions from the community to help make hipDNN better. This guide will help you understand the contribution process and requirements.

hipDNN is a graph-based deep learning library that enables multi-operation fusion for improved performance on AMD GPUs.

We're excited to have you join our community of contributors!

Before You Start

Before contributing, please review these essential documents to understand the project structure and goals:

• Design - Understand hipDNN's architecture and component design
• Building - Learn how to build hipDNN on your system
• How-To - Using hipDNN components and common approaches for extending functionality
• TestingStrategy - Understand our testing approach and requirements
• Roadmap - Check planned features and find contribution opportunities
• Coding Style and Naming Guidelines - Follow our coding conventions for consistency

We encourage you to open a GitHub issue to discuss your planned contribution before starting work. This helps ensure your efforts align with project goals and prevents duplicate work.

Contribution Requirements

All contributions must meet the following requirements before they can be merged:

Feature Proposals & RFCs

• RFC Process: For large or complex feature changes, contributors must provide a Request for Comments (RFC) proposal ahead of development.
  • This proposal should be discussed and iterated upon with maintainers prior to beginning feature work and implementation.
  • RFCs should be submitted as a Markdown document added to hipdnn/docs/rfcs via a Pull Request (e.g., see PR #3266).
• Phased Implementation: We strongly encourage landing changes in multiple phases.
• Small PRs: Please keep Pull Requests small and focused.
  • This makes reviews easier to digest.
  • It minimizes the potential for conflicts or large feature reverts if issues are discovered later.

Code Quality Standards

• Code Formatting: All code must follow the format specified by the .clang-format file
  • Run ninja format to auto-format your code
  • Run ninja check_format to verify formatting compliance
• Compiler Warnings: Code must compile without warnings
• Clang-tidy Compliance: Code must be free of clang-tidy errors

Testing Requirements

• Unit Tests: All new code must be covered by unit tests
• Integration Tests: Add integration tests where applicable to verify end-to-end functionality
• ASAN Compliance: All tests must run cleanly with AddressSanitizer enabled
  • Build with cmake -DBUILD_ADDRESS_SANITIZER=ON ..
  • Run tests with ninja check to verify ASAN compliance
  • Note: Some HIP-related tests may be skipped due to AddressSanitizer incompatibility
• GPU Test Handling:
  • Mark GPU-dependent tests with SKIP_IF_NO_DEVICE()
  • Tests must be skippable without GPU (warnings, not errors)
• Test Coverage:
  • Maintain overall 80% code coverage target
  • New code should not decrease existing coverage
  • Each component should maintain >80% coverage individually

See Testing for further details.

Documentation Requirements

• Update Documentation: Update all relevant documentation to reflect your changes
• Remove Stale Documentation: Remove any documentation that becomes obsolete due to your changes
• Clear PR details: Write clear and descriptive pull request details to help reviewers understand the changes

Architecture Considerations

When contributing to hipDNN, please keep these architectural principles in mind:

Dependency Management

• hipDNN Core (backend, SDK, frontend) should remain very light on dependencies
  • Avoid adding new library dependencies to the backend if possible
  • No compiled libraries required for the frontend or SDK (should remain header-only projects)
  • Any new dependencies require discussion and strong justification

Plugin Development

• Plugins are separate projects from hipDNN core
  • Plugins can have their own dependencies as needed
  • See Plugin Development for further guidance

Development Workflow

1. Fork and Clone

# Fork the repository on GitHub, then:
git clone https://github.com/YOUR_USERNAME/rocm-libraries.git
cd rocm-libraries
git remote add upstream https://github.com/ROCm/rocm-libraries.git

2. Create a Feature Branch

git checkout -b feature/your-feature-name

3. Build Locally

Follow the remaining instructions in the Quick Start Guide to build hipDNN.

4. Set Up Pre-commit Hooks

hipDNN uses pre-commit hooks to automatically validate code quality. See the main contributing guide for general pre-commit setup instructions.

Installing flatc (Required for hipDNN)

hipDNN requires flatc version 25.9.23 for the FlatBuffers schema compiler. Install it before setting up pre-commit:

Linux:

wget https://github.com/google/flatbuffers/releases/download/v25.9.23/Linux.flatc.binary.g++-13.zip
unzip Linux.flatc.binary.g++-13.zip
sudo mv flatc /usr/local/bin/
sudo chmod +x /usr/local/bin/flatc
rm Linux.flatc.binary.g++-13.zip

Windows:

1. Download: https://github.com/google/flatbuffers/releases/download/v25.9.23/Windows.flatc.binary.zip.
2. Extract flatc.exe and add it to your system PATH.

Verify installation:

flatc --version
# Should output: flatc version 25.9.23

After flatc is installed, set up pre-commit:

pip install pre-commit
pre-commit install

5. Run All Required Checks

Before submitting your PR, ensure all checks pass:

# Format code
ninja format

# Check formatting
ninja check_format

# Run all tests
ninja check

# Run tests with ASAN
cmake -DBUILD_ADDRESS_SANITIZER=ON ..
ninja check

# Check code coverage (optional but recommended)
cmake -DHIPDNN_ENABLE_COVERAGE=ON ..
ninja code_coverage

5. Create a Pull Request

• Push your changes to your fork
• Create a pull request against the main hipDNN repository
• Fill out the pull request template completely
• Ensure all CI checks pass

Pull Request Checklist

When creating a pull request, ensure you can check all these boxes:

• I have added automated tests relevant to the introduced functionality
• I have sufficient test coverage for the changes, and code coverage hasn't decreased
• I have run the tests, and they are all passing locally
• I have run the tests with ASAN, and they are all passing locally
• I have added relevant documentation for the changes
• I have removed stale documentation that is no longer relevant
• I have run make format & make check_format to ensure proper formatting

Getting Help

• Questions: Open a GitHub issue with your question
• Discussion: For design discussions or feature proposals, open an issue before starting work
• RFCs: For large or complex features, submitting an RFC is a great way to get early feedback on your design
• Draft PRs: Feel free to open a draft PR early to get feedback on your approach
• CI Pipelines: In your PR, ask members of the hipDNN team to run CI on your branch
• Code Reviews: Be responsive to code review feedback and make requested changes promptly

Community Guidelines

• Be respectful and constructive in all interactions
• Help review other contributors' PRs when possible
• Share knowledge and help newcomers get started

Thank you for contributing to hipDNN!