Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
91 lines (71 loc) · 4.84 KB

CONTRIBUTING.md

File metadata and controls

91 lines (71 loc) · 4.84 KB
Raw

Contributing to TorchTitan on TPU

This repository is Google's distribution of TorchTitan, adding training on Cloud TPU through TorchTPU. It tracks upstream closely, and we intend to keep it that way.

Issues

Bugs and feature requests for TPU support go to this repository's issue tracker. Problems in shared TorchTitan code that also reproduce off TPU belong upstream. When in doubt, file here and we will redirect it. A clear, well-isolated bug report is itself a valuable contribution, and for anything more than a trivial fix, filing an issue first lets us agree on the shape of the solution before you write code.

A good report carries what happened against what you expected with the full traceback, the recipe and exact launch command that reproduces it, and your environment: torch, torch_tpu and libtpu versions, TPU generation and topology, and whether the run was single-host or multi-host.

Where your change belongs

Please keep changes inside torchtitan/experiments/tpu. Everything outside it is upstream code that we re-sync from pytorch/torchtitan, so an edit there is either reverted by the next sync or becomes a conflict that someone resolves by hand.

  • TPU recipes, kernels, trainer, overrides and tests: here, under torchtitan/experiments/tpu.
  • Shared TorchTitan code (trainer, parallelism, models, components): send it to pytorch/torchtitan; it reaches this repository on the next sync.
  • Shared code that the TPU lane needs and upstream has not taken yet: please open an issue here first. A small, device-neutral extension point upstream beats a local fork of the file.

Before you begin

Contributions to this project must be accompanied by a Google Contributor License Agreement (CLA). You (or your employer) retain the copyright to your contribution; signing simply gives us permission to redistribute your changes. Visit https://cla.developers.google.com/ to see your agreements or to sign a new one. If you have already signed the Google CLA for another open-source project, you likely do not need to sign it again. A CLA bot checks pull requests automatically and guides you if action is needed.

This project follows Google's Open Source Community Guidelines.

Pull requests

Small and focused beats large and sprawling.

Approved pull requests are copied into Google's internal repository by a tool called Copybara. For this reason Copybara does not mark a pull request as merged: it closes the pull request and separately applies a commit to main with the same changes. Your change has landed when that commit appears.

Upstream's CONTRIBUTING covers the review standards for TorchTitan code, and we do not restate them here. For a change under torchtitan/experiments/tpu, please also show:

  • It trains: at least 10 steps on the relevant recipe, loss decreasing, no NaN or inf, with conclusions drawn from steps past warmup.
  • Its numerics: bit-identical (step-1 loss and grad_norm unchanged), rounding-order (fp32 round-off from tiling, fused kernels or reduction order), or semantic. A semantic change is a separate, labelled recipe rather than a performance lever.
  • That the mechanism fired: kernels verified in the HLO dump, since eager log lines do not print under torch.compile.
  • Performance, and the command behind it: step time, TPS, MFU and peak HBM on stated hardware and topology.
  • A recipe, for a new model: a per-topology config under torchtitan/experiments/tpu/recipes, plus a README carrying the launch block.

torchtitan/experiments/tpu/README.md has the setup and launch instructions; the TorchTPU optimization guide has the tuning levers.

AI-generated code

Use of AI assistants is neither encouraged nor discouraged, but the author is fully responsible for the code they submit: you must be able to explain and maintain it, and it must be correct and tested. Pull requests that appear to be unreviewed automated output will be closed. AI assistants are not co-authors; if one provided meaningful help, you may add an Assisted-by: tag in the commit message.

Security

Please report potential security vulnerabilities through http://g.co/vulnz rather than in a public issue; see SECURITY.md. High memory usage, crashes caused by invalid inputs, and numerical divergence from untrusted models are ordinary bugs rather than security vulnerabilities: running untrusted model code is equivalent to running untrusted arbitrary Python code.