Skip to content

Minor developer policy edits for clarity #132313

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rnk merged 2 commits into from
Mar 21, 2025
Merged

Minor developer policy edits for clarity #132313

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
42cf93e
Minor developer policy edits for clarity
rnk Mar 21, 2025
e9c5c1b
fix rst doc errors
rnk Mar 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 50 additions & 54 deletions llvm/docs/DeveloperPolicy.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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
----------------------

Expand Down