From 42cf93ec44819b582e5e4f076c236c7750c7647c Mon Sep 17 00:00:00 2001 From: Reid Kleckner Date: Fri, 21 Mar 2025 00:00:01 +0000 Subject: [PATCH 1/2] Minor developer policy edits for clarity 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. --- llvm/docs/DeveloperPolicy.rst | 104 ++++++++++++++++------------------ 1 file changed, 50 insertions(+), 54 deletions(-) diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst index 14abd4c67ae2a..7016b86f09dcf 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 `. - 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 `_ - * `libc++ vendors `_ - - 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 `_ 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 `_ 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 ---------------------- From e9c5c1b94cdc85be02fc281d449a42c7dfc7def3 Mon Sep 17 00:00:00 2001 From: Reid Kleckner Date: Fri, 21 Mar 2025 00:08:30 +0000 Subject: [PATCH 2/2] fix rst doc errors --- llvm/docs/DeveloperPolicy.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/llvm/docs/DeveloperPolicy.rst b/llvm/docs/DeveloperPolicy.rst index 7016b86f09dcf..376ce704c0639 100644 --- a/llvm/docs/DeveloperPolicy.rst +++ b/llvm/docs/DeveloperPolicy.rst @@ -654,8 +654,8 @@ awareness of. For such changes, the following should be done: 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`_ + * `Clang vendors `_ + * `libc++ vendors `_ People interested in joining the vendors group can do so by clicking the "Join team" button on the linked github pages above.