Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
111 lines (79 loc) · 3.89 KB

CONTRIBUTING.md

File metadata and controls

111 lines (79 loc) · 3.89 KB
Raw

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.
  • 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,jax]'

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.

Updating Reference Outputs

Several regression tests compare freshly generated CSV outputs against checked-in reference CSVs. When an intentional code change legitimately alters those outputs, you can refresh the references in-place by passing the --update-references flag to pytest:

python -m pytest tests/test_perf_report_regression.py --update-references

⚠️ Important: When you use --update-references in a PR, explicitly note in your PR description which reference files were updated and why.

Do not use this flag to paper over unexpected differences. If a test starts failing, first investigate why the output changed. Only refresh references once you have confirmed the new output is intentionally correct (e.g. a deliberate metric formula change, a new column, or a bug fix in the reporting pipeline).