[llvm] 5b09079 - Minor developer policy edits for clarity (#132313)

[via llvm-commits]

Author: Reid Kleckner
Date: 2025-03-21T13:29:24-07:00
New Revision: 5b090793744ad892166e97a7b2c05ddf904d915b

URL: https://github.com/llvm/llvm-project/commit/5b090793744ad892166e97a7b2c05ddf904d915b
DIFF: https://github.com/llvm/llvm-project/commit/5b090793744ad892166e97a7b2c05ddf904d915b.diff

LOG: Minor developer policy edits for clarity (#132313)

There should be no substantial policy change here.

I reordered the breaking change docs after the major change docs, since
that flow made sense to me. I smoothed out some of the incremental
development policy wording to be a bit less black and white, and talk
about "preferred" and "discouraged" approaches.

Added: 
    

Modified: 
    llvm/docs/DeveloperPolicy.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst
index 14abd4c67ae2a..376ce704c0639 100644
--- a/llvm/docs/DeveloperPolicy.rst
+++ b/llvm/docs/DeveloperPolicy.rst
@@ -129,57 +129,6 @@ LLVM has a code-review policy. Code review is one way to increase the quality of
 software. Please see :doc:`CodeReview` for more information on LLVM's code-review
 process.
 
-.. _breaking:
-
-Making Potentially Breaking Changes
------------------------------------
-
-Please help notify users and vendors of potential disruptions when upgrading to
-a newer version of a tool. For example, deprecating a feature that is expected
-to be removed in the future, removing an already-deprecated feature, upgrading a
-diagnostic from a warning to an error, switching important default behavior, or
-any other potentially disruptive situation thought to be worth raising
-awareness of. For such changes, the following should be done:
-
-.. warning::
-
-  Phabricator is deprecated and is available in read-only mode,
-  for new code contributions use :ref:`GitHub Pull Requests <github-reviews>`.
-  This section contains old information that needs to be updated.
-
-* When performing the code review for the change, please add any applicable
-  "vendors" group to the review for their awareness. The purpose of these
-  groups is to give vendors early notice that potentially disruptive changes
-  are being considered but have not yet been accepted. Vendors can give early
-  testing feedback on the changes to alert us to unacceptable breakages. The
-  current list of vendor groups is:
-
-  * `Clang vendors <https://reviews.llvm.org/project/members/113/>`_
-  * `libc++ vendors <https://reviews.llvm.org/project/members/109/>`_
-
-  People interested in joining the vendors group can do so by clicking the
-  "Join Project" link on the vendor's "Members" page in Phabricator.
-
-* When committing the change to the repository, add appropriate information
-  about the potentially breaking changes to the ``Potentially Breaking Changes``
-  section of the project's release notes. The release note should have
-  information about what the change is, what is potentially disruptive about
-  it, as well as any code examples, links, and motivation that is appropriate
-  to share with users. This helps users to learn about potential issues with
-  upgrading to that release.
-
-* After the change has been committed to the repository, the potentially
-  disruptive changes described in the release notes should be posted to the
-  `Announcements <https://discourse.llvm.org/c/announce/>`_ channel on
-  Discourse. The post should be tagged with the ``potentially-breaking`` label
-  and a label specific to the project (such as ``clang``, ``llvm``, etc). This
-  is another mechanism by which we can give pre-release notice to users about
-  potentially disruptive changes. It is a lower-traffic alternative to the
-  joining "vendors" group. To automatically be notified of new announcements
-  with the ``potentially-breaking`` label, go to your user preferences page in
-  Discourse, and add the label to one of the watch categories under
-  ``Notifications->Tags``.
-
 .. _maintainers:
 
 Maintainers
@@ -632,9 +581,11 @@ as a series of `incremental changes`_, not as a long-term development branch.
 Incremental Development
 -----------------------
 
-In the LLVM project, we do all significant changes as a series of incremental
-patches.  We have a strong dislike for huge changes or long-term development
-branches.  Long-term development branches have a number of drawbacks:
+In the LLVM project, we prefer the incremental development approach, where
+significant changes are developed in-tree incrementally. The alternative
+approach of implementing features in long-lived development branches or forks
+is discouraged, although we have accepted features developed this way in the
+past. Long-term development branches have a number of drawbacks:
 
 #. Branches must have mainline merged into them periodically.  If the branch
    development and mainline development occur in the same pieces of code,
@@ -684,6 +635,51 @@ If you are interested in making a large change, and this scares you, please make
 sure to first `discuss the change/gather consensus`_ then ask about the best way
 to go about making the change.
 
+.. _breaking:
+
+Making Potentially Breaking Changes
+-----------------------------------
+
+Please help notify users and vendors of potential disruptions when upgrading to
+a newer version of a tool. For example, deprecating a feature that is expected
+to be removed in the future, removing an already-deprecated feature, upgrading
+a diagnostic from a warning to an error, switching important default behavior,
+or any other potentially disruptive situation thought to be worth raising
+awareness of. For such changes, the following should be done:
+
+* When performing the code review for the change, please add any applicable
+  "vendors" github team to the review for their awareness. The purpose of these
+  groups is to give vendors early notice that potentially disruptive changes
+  are being considered but have not yet been accepted. Vendors can give early
+  testing feedback on the changes to alert us to unacceptable breakages. The
+  current list of vendor groups is:
+
+  * `Clang vendors <https://github.com/orgs/llvm/teams/clang-vendors>`_
+  * `libc++ vendors <https://github.com/orgs/llvm/teams/libcxx-vendors>`_
+
+  People interested in joining the vendors group can do so by clicking the
+  "Join team" button on the linked github pages above.
+
+* When committing the change to the repository, add appropriate information
+  about the potentially breaking changes to the ``Potentially Breaking Changes``
+  section of the project's release notes. The release note should have
+  information about what the change is, what is potentially disruptive about
+  it, as well as any code examples, links, and motivation that is appropriate
+  to share with users. This helps users to learn about potential issues with
+  upgrading to that release.
+
+* After the change has been committed to the repository, the potentially
+  disruptive changes described in the release notes should be posted to the
+  `Announcements <https://discourse.llvm.org/c/announce/>`_ channel on
+  Discourse. The post should be tagged with the ``potentially-breaking`` label
+  and a label specific to the project (such as ``clang``, ``llvm``, etc). This
+  is another mechanism by which we can give pre-release notice to users about
+  potentially disruptive changes. It is a lower-traffic alternative to the
+  joining "vendors" group. To automatically be notified of new announcements
+  with the ``potentially-breaking`` label, go to your user preferences page in
+  Discourse, and add the label to one of the watch categories under
+  ``Notifications->Tags``.
+
 Attribution of Changes
 ----------------------