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 `. - 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 `_ + * `libc++ 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 ----------------------