New feature ideas are best discussed on a specific issue. Please include
as much information as you can, any accompanying data, and your proposed
solution. The PyTorch team and community frequently review new issues
and comments where they think they can help. If you feel confident in
your solution, go ahead and implement it.

Reporting Issues
~~~~~~~~~~~~~~~~

If you've identified an issue, first search through the `list of
existing issues <https://github.com/pytorch/pytorch/issues>`__ on the
repo. If you are unable to find a similar issue, then create a new one.
Supply as much information you can to reproduce the problematic
behavior. Also, include any additional insights like the behavior you
expect.

Implementing Features or Fixing Bugs

A great deal of the tutorials on `pytorch.org <https://pytorch.org/>`__
come from the community itself and we welcome additional contributions.
To learn more about how to contribute a new tutorial you can learn more
here: `PyTorch.org Tutorial Contribution Guide on
GitHub <https://github.com/pytorch/tutorials/#contributing>`__

Improving Documentation & Tutorials

You can find active discussions happening on the `PyTorch Discussion
Forums <https://discuss.pytorch.org/>`__  for users as well as the
`PyTorch Dev Discussion Forums <https://dev-discuss.pytorch.org/>`__
for developers and maintainers.

Submitting Pull Requests to Fix Open Issues

We appreciate your help reviewing and commenting on pull requests. Our
team strives to keep the number of open pull requests at a manageable
size, we respond quickly for more information if we need it, and we
merge PRs that we think are useful. However, due to the high level of
interest, additional eyes on the pull requests are always appreciated.

Improving Code Readability
~~~~~~~~~~~~~~~~~~~~~~~~~~

Improving code readability helps everyone. It is often better to submit a
small number of pull requests that touch a few files versus a large pull
request that touches many files. Starting a discussion in the PyTorch
forum `here <https://discuss.pytorch.org/>`__ or on an issue related to
your improvement is the best way to get started.

Adding Test Cases to Make the Codebase More Robust

Your use of PyTorch in your projects, research papers, write ups, blogs,
or general discussions around the internet helps to raise awareness for
PyTorch and our growing community. Please reach out to
`[email protected] <mailto:[email protected]>`__
for marketing support.

Triaging Issues
~~~~~~~~~~~~~~~

If you feel that an issue could benefit from a particular tag or level
of complexity, comment on the issue and share your opinion. If you
feel an issue isn't categorized properly, comment and let the team know.

About Open Source Development
-----------------------------

If this is your first time contributing to an open source project, some
aspects of the development process may seem unusual to you.

-  **There is no way to “claim” issues.** People often want to “claim”
   an issue when they decide to work on it, to ensure that there isn't
   wasted work when someone else ends up working on it. This doesn't
   really work too well in open source, since someone may decide to work
   on something, and end up not having time to do it. Feel free to give
   information in an advisory fashion, but at the end of the day, we
   will take running code and rough consensus to move forward quickly.
-  **There is a high bar for new functionality.** Unlike
   in a corporate environment, where the person who wrote code
   implicitly “owns” it and can be expected to take care of it for the
   code's lifetime, once a pull request is merged into an open
   source project, it immediately becomes the collective responsibility
   of all maintainers on the project. When we merge code, we are saying
   that we, the maintainers, can review subsequent changes and
   make a bugfix to the code. This naturally leads to a higher standard
   of contribution.

Common Mistakes To Avoid
------------------------

-  **Did you add tests?** (Or if the change is hard to test, did you
   describe how you tested your change?)

   -  We have a few motivations for why we ask for tests:

      1. to help us tell if we break it later
      2. to help us tell if the patch is correct in the first place
         (yes, we did review it, but as Knuth says, “beware of the
         following code, for I have not run it, merely proven it
         correct”)

   -  When is it OK not to add a test? Sometimes a change can't be
      conveniently tested, or the change is so obviously correct (and
      unlikely to be broken) that it's OK not to test it. On the
      contrary, if a change seems likely (or is known to be likely)
      to be accidentally broken, it's important to put in the time to
      work out a testing strategy.

-  **Is your PR too long?**

   -  It's easier for us to review and merge small PRs. The difficulty of
      reviewing a PR scales nonlinearly with its size.
   -  When is it OK to submit a large PR? It helps a lot if there was a
      corresponding design discussion in an issue, with sign off from
      the people who are going to review your diff. We can also help
      give advice about how to split up a large change into individually
      shippable parts. Similarly, it helps if there is a complete
      description of the contents of the PR: it's easier to review code
      if we know what's inside!

-  **Comments for subtle things?** In cases where the behavior of your code
   is nuanced, please include extra comments and documentation to allow
   us to better understand the intention of your code.
-  **Did you add a hack?** Sometimes, the right answer is a hack. But
   usually, we will have to discuss it.
-  **Do you want to touch a very core component?** To prevent
   major regressions, pull requests that touch core components receive
   extra scrutiny. Make sure you've discussed your changes with the team
   before undertaking major changes.
-  **Want to add a new feature?** If you want to add new features,
   comment your intention on the related issue. Our team tries to
   comment on and provide feedback to the community. It's better to have
   an open discussion with the team and the rest of the community before
   building new features. This helps us stay aware of what you're
   working on and increases the chance that it'll be merged.
-  **Did you touch code unrelated to the PR?** To aid in code review,
   please only include files in your pull request that are directly
   related to your changes.

Frequently Asked Questions
--------------------------

-  **How can I contribute as a reviewer?** There is lots of value if
   community developers reproduce issues, try out new functionality, or
   otherwise help us identify or troubleshoot issues. Commenting on
   tasks or pull requests with your environment details is helpful and
   appreciated.
-  **CI tests failed, what does it mean?** Maybe your PR is based
   off a broken main branch? You can try to rebase your change on top
   of the latest main branch. You can also see the current status of
   main branch's CI at https://hud.pytorch.org/.
-  **What are the most high risk changes?** Anything that touches build
   configuration is a risky area. Please avoid changing these unless
   you've had a discussion with the team beforehand.
-  **Hey, a commit showed up on my branch, what's up with that?**
   Sometimes another community member will provide a patch or fix to
   your pull request or branch. This is often needed for getting CI tests
   to pass.

On Documentation
----------------

Python Docs
~~~~~~~~~~~

PyTorch documentation is generated from python source using
`Sphinx <https://www.sphinx-doc.org/en/master/>`__. Generated HTML is
copied to the docs folder in the main branch of
`pytorch.org/docs <https://pytorch.org/docs/main>`__,
and is served via GitHub pages.

-  Site: https://pytorch.org/docs
-  GitHub: https://github.com/pytorch/pytorch/tree/main/docs
-  Served from:
   `https://pytorch.org/docs/main <https://pytorch.org/docs/main>`__

C++ Docs
~~~~~~~~

For C++ code we use Doxygen to generate the content files. The C++ docs
are built on a special server and the resulting files are copied to the
https://github.com/pytorch/cppdocs repo, and are served from GitHub
pages.

-  Site: https://pytorch.org/cppdocs
-  GitHub: https://github.com/pytorch/pytorch/tree/main/docs/cpp
-  Served from: https://github.com/pytorch/cppdocs

Tutorials
---------

PyTorch tutorials are documents used to help understand using PyTorch to
accomplish specific tasks or to understand more holistic concepts.
Tutorials are built using
`Sphinx-Gallery <https://sphinx-gallery.readthedocs.io/en/latest/index.html>`__
from executable python source files, or from restructured-text (rst)
files.

-  Site: https://pytorch.org/tutorials
-  GitHub: https://github.com/pytorch/tutorials

Tutorials Build Overview

See `PyTorch.org Tutorial Contribution
Guide <https://github.com/pytorch/tutorials/#contributing>`__.