TheRock/rocm-systems/projects/rocprofiler-compute/CONTRIBUTING.md

Contributing to ROCm Compute Profiler

Getting Started

ROCm Compute Profiler lives under projects/rocprofiler-compute in the ROCm Systems super-repo. To set up your local environment, follow the clone and setup instructions in the rocm-systems CONTRIBUTING.md. Sparse checkout is recommended for most contributors.

Reporting Issues and Bugs

• Search existing issues before filing a new one — your bug may already be tracked.
• If you don't find an existing issue, open a new one with a clear description of the problem and steps to reproduce it.

Submitting a Pull Request

Follow the pull request guidelines in the rocm-systems CONTRIBUTING.md.

Note for external contributors: Please refer to the ROCm contribution guide for instructions on contributing from a fork.

Review and Labeling

Labels and reviewer assignments are handled automatically based on the files you've changed. Reviewers for projects/rocprofiler-compute are defined in the top-level CODEOWNERS file.

CI Requirements

All pull requests must pass CI checks before merging. For rocprofiler-compute, these currently include compilation checks, with correctness and performance tests being added over time. See the CI documentation for a full breakdown of what runs on each PR.

Tip

Run our pre-commit hooks locally before pushing to catch formatting issues early. See Using Pre-Commit Hooks below for setup instructions.

Adding Experimental Features

New features that aren't yet stable can be introduced behind the --experimental flag. This lets users opt in to preview functionality while keeping the default experience stable.

How It Works

The --experimental flag acts as a master toggle:

• Experimental options are hidden from help output unless --experimental is passed.
• Attempting to use an experimental flag without --experimental raises a clear error.
• A warning is displayed when an experimental feature is active.

To see available experimental features:

rocprof-compute profile --experimental --help

Adding a New Experimental Feature

Follow these three steps to add a new experimental flag.

Step 1 — Register it in the --experimental help text

In src/argparser.py, update the add_general_group() function:

general_group.add_argument(
    "--experimental",
    action="store_true",
    default=False,
    help=(
        "Enable experimental feature(s):\n"
        "   Your feature name (--your-flag)\n"  # Add this line
    ),
)

Step 2 — Add the argument using ExperimentalAction

Add your flag to the relevant parser group (profile, analyze, etc.):

# For a flag that accepts a value
profile_group.add_argument(
    "--your-flag",
    dest="your_flag",
    required=False,
    default=None,
    action=ExperimentalAction,
    experimental_enabled=experimental_enabled,
    feature_label="Your feature name",
    base_action="store",  # Required — see supported actions below
    type=str,
    nargs="*",
    metavar="",
    help="\t\t\tDescription of your feature",
)

# For a boolean toggle flag
analyze_group.add_argument(
    "--your-flag",
    dest="your_flag",
    required=False,
    default=False,
    action=ExperimentalAction,
    experimental_enabled=experimental_enabled,
    feature_label="Your feature description",
    base_action="store_const",  # Required — see supported actions below
    nargs=0,
    const=True,
    help="\t\tDescription of your feature",
)

The base_action parameter is required and must be one of:

Value	Behavior
store	Store a value (standard argparse default)
store_const	Store a fixed constant; consumes no arguments
store_true	Store True when the flag is present
store_false	Store False when the flag is present
append	Append each value to a list
append_const	Append a constant to a list
count	Count occurrences (e.g. -vvv)
extend	Extend a list with multiple values

Step 3 — Verify behavior

Confirm the flag is hidden without --experimental and visible with it:

# Should not appear
rocprof-compute profile --help

# Should appear with EXPERIMENTAL: prefix
rocprof-compute profile --experimental --help

Promoting a Feature to Stable

When a feature is ready for general availability:

1. Remove it from the --experimental help text in src/argparser.py.
2. Replace action=ExperimentalAction with a standard argparse action (e.g. action="store").
3. Remove the experimental_enabled, feature_label, and base_action parameters.
4. Update documentation and tests accordingly.

Using Pre-Commit Hooks

Pre-commit hooks automatically check your code for formatting issues before each commit, helping you catch problems before they reach CI.

Setup:

First, install development dependencies, then enable the hooks:

cd rocprofiler-compute
pre-commit install

Once installed, every commit will run the configured checks automatically:

See the pre-commit documentation for more details.

Code Style and Formatting

ROCm Compute Profiler uses Ruff for linting and formatting. All contributions to src/ must pass Ruff checks before merging. Pre-commit hooks handle this automatically.

Style references:

Topic	Source of Truth
Function design, naming, code organization	Python Coding Style Guidelines
Ruff configuration (enforced rules, ignores, formatting)	pyproject.toml
YAML metric equation formatting	YAML Metric Equation Formatting

Running Ruff Manually

# Check for issues
ruff check .
ruff format --check .

# Auto-fix most issues
ruff check --fix .
ruff format .

YAML Metric Equation Formatting

Metric equations in YAML config files follow a canonical format. The canonical implementation is tools/format_yaml.py.

Scope. Equation formatting applies to YAML files under:

• src/rocprof_compute_soc/analysis_configs/gfx*/*.yaml
• src/rocprof_compute_tui/utils/gfx*/*.yaml

Template files (*_template.yaml) and build artifacts are excluded. Only values under these keys are treated as equations: value, avg, min, max, peak.

Rules.

• Operator spacing — all binary operators (+, -, *, /) have exactly one space on each side: SUM(x) / SUM(y).
• Constant factoring — when an aggregation (SUM, AVG, MIN, MAX) multiplies by a numeric constant, factor it out: 128 * SUM(x), not SUM(x * 128). Addition inside aggregations is left as-is.
• Minimal parentheses — remove parentheses made redundant by operator precedence (a + b + c, not (a + b) + c), but preserve those required for correct evaluation (a - (b - c), (a + b) * c).
• Unary negation — negation of a compound expression keeps its parentheses: -(a + b), not -a + b.
• Literal values — N/A, None, null, true, false, and Peak (Empirical) are never parsed as equations and must be written exactly as shown (the space before ( in Peak (Empirical) is required).

Equations with unsupported syntax (unknown characters, unmatched parentheses) are left unchanged; the formatter never corrupts an equation it cannot fully parse.

Enforcement. The yaml-format-fix pre-commit hook runs tools/format_yaml.py --fix on staged config files and auto-corrects equations in place. Re-stage the modified files and commit again.

# Show proposed changes
python tools/format_yaml.py --diff src/rocprof_compute_soc/analysis_configs/gfx950/*.yaml

# Auto-fix in place
python tools/format_yaml.py --fix src/rocprof_compute_soc/analysis_configs/gfx950/*.yaml

Documentation Changes

For instructions on building and testing changes to files under the docs/ folder, see the ROCm documentation contributing guide.

Metrics Management

If your PR modifies metric configurations — panel YAMLs under src/rocprof_compute_soc/analysis_configs/gfx<arch>/*.yaml or metric descriptions in docs/data/metrics_description.yaml — follow the metric management workflow:

1. Edit the relevant panel YAMLs.
2. Validate them with python tools/config_management/master_config_workflow_script.py --validate-only.
3. Refresh the hash DB with python tools/config_management/hash_manager.py --compute-all src/rocprof_compute_soc/analysis_configs and confirm CI tests pass.

For full details, see the metric config management README.

Vendoring External Dependencies

rocprofiler-compute vendors certain Python dependencies (via git submodules) to eliminate external dependencies in profile mode. This improves portability and reliability on HPC systems.

We vendor:

• Pure Python packages used in profile code path
• Stable packages with permissive licenses

For detailed vendoring workflow (adding/updating packages), see src/vendored/README.md.

AI Agent Guidelines

This project uses AI coding assistants (Claude Code, Cursor, GitHub Copilot). All AI-specific guidelines live in AGENTS.md, which serves as the single source of truth. Tool-specific adapter files (e.g., CLAUDE.md, .github/copilot-instructions.md) reference AGENTS.md without duplicating content.

To add or update AI guidelines, edit the appropriate file under .ai/ and add a reference in AGENTS.md.

Profile Mode Dependency Policy

Profile mode code should not use non-standard Python libraries.

Why This Matters

Profile mode uses only stdlib to:

1. Avoid dependency conflicts - Users can profile without creating virtual environments or worrying about package version conflicts with their own projects
2. Work everywhere - No pip install needed:
   • HPC systems with locked-down Python environments
   • Security-sensitive systems requiring minimal dependencies
   • Any system with Python 3.8+ installed

Enforcement

Python Version Requirement:

• Import enforcement requires Python 3.10+ (uses sys.stdlib_module_names)
• Python 3.8-3.9: Tests run but import enforcement is disabled (warning issued)
• CI uses Python 3.10+ to ensure full enforcement coverage

Enforcement is automatically done for tests which execute profile pipeline using main function instead of subprocess (unlike tests using --call-binary and multi mpi rank tests). These tests are automatically protected by guards in tests/conftest.py when testing with Python 3.10 and above. The guard intercepts ALL imports (direct, nested, dynamic) and fails tests immediately if non-stdlib packages are imported.

What's Allowed

Python standard library (Python 3.8+):

• json, csv, sqlite3, subprocess, pathlib, logging, sys, os, etc.

Project modules:

• rocprof_compute, utils, vendored.*, roofline, config, argparser

ROCm system libraries (bundled with ROCm, not pip packages):

• amdsmi - AMD System Management Interface
• hip - HIP runtime Python bindings
• rocprofv3 - rocprofv3 Python bindings

What's NOT Allowed

These are forbidden in profile mode

External packages:

• pandas, yaml, numpy, plotly, dash, textual, etc.
• Anything from requirements.txt

Common Mistakes

Don't do this in profile code:

import pandas  # External package
import yaml    # Use json or vendored.pyyaml instead
import numpy   # Use stdlib math/statistics

Do this instead:

import json              # Stdlib for config/data
import csv               # Stdlib for CSV operations
import sqlite3           # Stdlib for data manipulation
from vendored.pyyaml import yaml  # Vendored package (if needed)

If Your Test Fails

Error message:

PROFILE MODE DEPENDENCY VIOLATION
Forbidden package: pandas

How to fix:

1. Move import to analyze mode

   • Move the import and relevant code to analysis mode

2. Use stdlib alternative

   • pandas → csv module + sqlite3 for dataframes
   • yaml → json module (or vendored.pyyaml if YAML required)
   • numpy → math/statistics modules