Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
151 lines (110 loc) · 4.83 KB

CONTRIBUTING.md

File metadata and controls

151 lines (110 loc) · 4.83 KB

Contributing to TraceLens

Thanks for your interest in improving TraceLens — a toolkit that parses PyTorch/JAX profiler traces and generates useful insights.

📋 Before You Start

⚠️ NOTE FOR AMDers:

This is a public repository. Do NOT add any private, confidential, or customer-related data, code, or information to this repo.

Please ensure all contributions are free of sensitive or proprietary content before submitting.

  • Read the README to understand scope and architecture.
  • Search existing issues and discussions to avoid duplicates.
  • For new features and enhancements (new analyser, backend integration, refactor), open an issue first to align on approach.
  • Prefer small, modular, focused PRs.
  • Have a ready-made utility? If your utility is already developed, you can raise a PR to add it directly to examples/custom_workflows/. This lets the community start using it right away while we plan a tighter integration into the core library.

Table of Contents

Dev Setup

# clone
git clone https://github.com/AMD-AGI/TraceLens.git

# optional: virtual env
python3 -m venv .venv
source .venv/bin/activate

# install (editable) + dev extras
pip install -U pip
pip install -e .[dev]

Project Structure (high level)

TraceLens/
├── TraceLens/
│   ├── Reporting/        # CLI tools for quick start utils
│   ├── Trace2Tree/       # Trace2Tree parses trace into tree data structure
│   ├── PerfModel/        # Op meta data parsing and performance modelling code (roofline, FLOPs/Byte, etc.)
│   ├── TreePerf/         # TreePerf uses Trace Tree and PerfModel to generate perf breakdowns and perf metrics TFLOPS/s, etc. 
|   |                     # This directory also contains GPUEventAnalyzer
│   ├── NcclAnalyser/     # Analysis of collective communications
│   ├── TraceFusion/      # Merging of multi‑rank traces into a global view
│   ├── TraceDiff/        # TraceDiff uses the Trace Tree format and does morphological comparison across traces
│   └── EventReplay/      # Extracts meta data and replays almost arbitrary operations
├── docs/               # tool-specific guides
├── examples/           # example traces, notebooks, scripts, custom-workflows
├── tests/              # unit & integration tests
└── setup.py

Code Formatting with Black

This project uses Black to automatically format Python code for consistency and readability.

Installing Black

You can install Black using pip:

pip install black

Using Black

To format all Python files in the project, run:

black .

You can also format a specific file:

black path/to/your_file.py

Please ensure your code is formatted with Black before submitting a pull request.

Branch Naming Convention

Please follow this branch naming convention for all feature and bug fix branches:

<type>/<scope>/<short-description>

Types (type)

Type Purpose
feat New feature or functionality
fix Bug fix
docs Documentation update
refactor Code refactoring (no functionality change)
test Tests and test-related changes
chore Miscellaneous changes (e.g., build scripts)
ci Continuous integration-related changes

Scope (optional)

The scope can be used to specify which part of the project is affected, for example: trace2tree, perfmodel, tracediff, docs, tests.

Examples

feat/perfmodel/aiter-fav3
fix/tracediff/diff-reporting-bug
docs/update-jax-docs
refactor/trace2tree/remove-dead-code
ci/add-linting-automation

Commit Message Convention

We follow Conventional Commits for commit messages. Example:

feat(perfmodel): add perf model for aiter fav3
fix(tracediff): resolve diff reporting error
docs(readme-tracediff): add docs for jax tracediff

This format helps us to automatically generate changelogs and provide more clarity in versioning.