[llvm] [docs] Refresh Developer Policy text (PR #136198)

Fri Apr 18 04:26:39 PDT 2025

================
@@ -16,90 +16,87 @@ to eliminate miscommunication, rework, and confusion that might arise from the
 distributed nature of LLVM's development.  By stating the policy in clear terms,
 we hope each developer can know ahead of time what to expect when making LLVM
 contributions.  This policy covers all llvm.org subprojects, including Clang,
-LLDB, libc++, etc.
+LLDB, libc++, MLIR, etc.
 
-This policy is also designed to accomplish the following objectives:
+The developer policy supports the following LLVM project objectives:
 
-#. Attract both users and developers to the LLVM project.
+#. Attract both users and new contributors to the LLVM project.
 
-#. Make life as simple and easy for contributors as possible.
+#. Help people contribute to LLVM by documenting our development practices.
 
-#. Keep the top of tree as stable as possible.
+#. Maintain the stability, performance, and quality of the ``main`` branch.
 
-#. Establish awareness of the project's :ref:`copyright, license, and patent
-   policies <copyright-license-patents>` with contributors to the project.
-
-This policy is aimed at frequent contributors to LLVM. People interested in
-contributing one-off patches can do so in an informal way by sending them to the
-`llvm-commits mailing list
-<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_ and engaging another
-developer to see it through the process.
+#. Establish the project's :ref:`copyright, license, and patent
+   policies <copyright-license-patents>` policies.
 
 Developer Policies
 ==================
 
-This section contains policies that pertain to frequent LLVM developers.  We
-always welcome `one-off patches`_ from people who do not routinely contribute to
-LLVM, but we expect more from frequent contributors to keep the system as
-efficient as possible for everyone.  Frequent LLVM contributors are expected to
-meet the following requirements in order for LLVM to maintain a high standard of
-quality.
-
-Stay Informed
--------------
-
-Developers should stay informed by reading the `LLVM Discourse forums`_ and subscribing
-to the categories of interest for notifications.
-
-Paying attention to changes being made by others is a good way to see what other people
-are interested in and watching the flow of the project as a whole.
+Communication Channels
+----------------------
 
-Contibutions to the project are made through :ref:`GitHub Pull Requests <github-reviews>`.
-You can subscribe to notification for areas of the codebase by joining
+LLVM is a large project with many subcomponents, and it has a wide array of
+communication channels that you can use to keep track of recent developments,
+upcoming projects, new designs, enhancements, and other community business.
+
+First and foremost is the `LLVM Discourse forums`_, which is the successor
+to our former mailing lists (llvm-dev@, cfe-dev@, lldb-dev@, etc). This is
+probably the most vital and active communication channel to our highly
+distributed open source project. It enables long-form asyncronous text
+communication, and this is where people tend to propose major changes or
+propose new designs in the form of RFCs (Request For Comment), which are
+described later. Please be aware that the discourse forums are public and
+archived, and that notices of confidentiality or non-disclosure cannot be
+respected.
+
+We accept code contributions as :ref:`GitHub Pull Requests <github-reviews>`.
+Our project is generally too large to subscribe to all github notifications, so
+if you want to be notified of pull requests affecting a specific parts of the
+code, you can join
 one of the `pr-subscribers-* <https://github.com/orgs/llvm/teams?query=pr-subscribers>`_
 GitHub teams. This `mapping <https://github.com/llvm/llvm-project/blob/main/.github/new-prs-labeler.yml>`_
-indicates which team is associated with a particular paths in the repository.
-
-You can also subscribe to the "commits" mailing list for a subproject you're interested in,
-such as `llvm-commits
-<http://lists.llvm.org/mailman/listinfo/llvm-commits>`_, `cfe-commits
-<http://lists.llvm.org/mailman/listinfo/cfe-commits>`_, or `lldb-commits
-<http://lists.llvm.org/mailman/listinfo/lldb-commits>`_.
+documents the paths that trigger notifications for each of the listed teams.
 
 Missing features and bugs are tracked through our `GitHub issue tracker <https://github.com/llvm/llvm-project/issues>`_
-and assigned labels. We recommend that active developers monitor incoming issues.
-You can subscribe for notification for specific components by joining
-one of the `issue-subscribers-* <https://github.com/orgs/llvm/teams?query=issue-subscribers>`_
-teams.
-You may also subscribe to the `llvm-bugs
-<http://lists.llvm.org/mailman/listinfo/llvm-bugs>`_ email list to keep track
-of bugs and enhancements occurring in the entire project.  We really appreciate people
-who are proactive at catching incoming bugs in their components and dealing with them
-promptly.
-
-Please be aware that all public LLVM mailing lists and discourse forums are public and archived, and
-that notices of confidentiality or non-disclosure cannot be respected.
+and assigned labels. You can subscribe for notification for specific components
+by joining
+one of the `issue-subscribers-*
+<https://github.com/orgs/llvm/teams?query=issue-subscribers>`_ teams. You may
+also subscribe to the `llvm-bugs
+<http://lists.llvm.org/mailman/listinfo/llvm-bugs>`_ email list to subscribe to
+the firehose of all issue notifications, which some community members use to
+perform custom filtering.
+
+Beyond the main formal communication channels, LLVM has a Discord server for
+real-time chat communication, as well as a community calendar with many regular
+workgroup video calls and office hours. See :doc:`GettingInvolved` for more
+information on other ways to engage with the community.
 
 .. _patch:
-.. _one-off patches:
 
 Making and Submitting a Patch
 -----------------------------
 
-When making a patch for review, the goal is to make it as easy for the reviewer
-to read it as possible.  As such, we recommend that you:
+Submitting patches for review is straightforward with GitHub. Follow the
+:ref:`Getting Started Guide <sources>` to check out sources, make a patch, and
+then follow the :ref:`GitHub Pull Request <github-reviews>` guide to upload a
+pull request.
 
-#. Make your patch against git main, not a branch, and not an old version
-   of LLVM.  This makes it easy to apply the patch.  For information on how to
-   clone from git, please see the :ref:`Getting Started Guide <sources>`.
+Here are some tips to enable a successful code review:
 
-#. Similarly, patches should be submitted soon after they are generated.  Old
-   patches may not apply correctly if the underlying code changes between the
-   time the patch was created and the time it is applied.
+* :ref:`Include a test <include a testcase>`. This tends to be one of the first
+  things a reviewer will ask for and look at to understand what a new patch
+  does.
 
-#. Once you have created your patch, create a
-   :ref:`GitHub Pull Request <github-reviews>` for
-   it (or commit it directly if applicable).
+* Identify 2-3 individuals to review the patch. Look through the relevant
+  :ref:`Maintainers` file or browse git blame for likely stakeholders for the
+  code want to modify.
+
+* Make sure your patch is based on a recent commit from ``main``, rather than a
+  previous release branch. If you want to make changes to a release branch, land
----------------
AaronBallman wrote:

```suggestion
* To avoid precommit CI failures due to merge conflicts, base your patches on a recent commit from ``main``. If you want to make changes to a release branch, land
```
Maybe? It explains why this is needed.

https://github.com/llvm/llvm-project/pull/136198
