release notes so that it's clear to external users who do not follow the
project how the C API is changing and evolving.
-New Targets
------------
+.. _toolchain:
+
+Updating Toolchain Requirements
+-------------------------------
+
+We intend to require newer toolchains as time goes by. This means LLVM's
+codebase can use newer versions of C++ as they get standardized. Requiring newer
+toolchains to build LLVM can be painful for those building LLVM; therefore, it
+will only be done through the following process:
+
+ * It is a general goal to support LLVM and GCC versions from the last 3 years
+ at a minimum. This time-based guideline is not strict: we may support much
+ older compilers, or decide to support fewer versions.
+
+ * An RFC is sent to the `llvm-dev mailing list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_
+
+ - Detail upsides of the version increase (e.g. which newer C++ language or
+ library features LLVM should use; avoid miscompiles in particular compiler
+ versions, etc).
+ - Detail downsides on important platforms (e.g. Ubuntu LTS status).
+
+ * Once the RFC reaches consensus, update the CMake toolchain version checks as
+ well as the :doc:`getting started<GettingStarted>` guide. This provides a
+ softer transition path for developers compiling LLVM, because the
+ error can be turned into a warning using a CMake flag. This is an important
+ step: LLVM still doesn't have code which requires the new toolchains, but it
+ soon will. If you compile LLVM but don't read the mailing list, we should
+ tell you!
+
+ * Ensure that at least one LLVM release has had this soft-error. Not all
+ developers compile LLVM top-of-tree. These release-bound developers should
+ also be told about upcoming changes.
+
+ * Turn the soft-error into a hard-error after said LLVM release has branched.
+
+ * Update the :doc:`coding standards<CodingStandards>` to allow the new
+ features we've explicitly approved in the RFC.
+
+ * Start using the new features in LLVM's codebase.
+
+Here's a `sample RFC
+<http://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html>`_ and the
+`corresponding change <https://reviews.llvm.org/D57264>`_.
+
+.. _new-llvm-components:
+
+Introducing New Components into LLVM
+====================================
+
+The LLVM community is a vibrant and exciting place to be, and we look to be
+inclusive of new projects and foster new communities, and increase
+collaboration across industry and academia.
+
+That said, we need to strike a balance between being inclusive of new ideas and
+people and the cost of ongoing maintenance that new code requires. As such, we
+have the following general policies for introducing major new components into
+the LLVM world. However, this is really only intended to cover common cases
+that we have seen arise: different situations are different, and we are open
+to discussing unusual cases as well - just start an RFC thread on the
+`llvm-dev mailing list <https://lists.llvm.org/mailman/listinfo/llvm-dev>`_.
+
+Adding a New Target
+-------------------
LLVM is very receptive to new targets, even experimental ones, but a number of
problems can appear when adding new large portions of code, and back-ends are
status, but also markers to define bit-rot, and will be used to clean up the
tree from unmaintained targets.
-.. _toolchain:
-
-Updating Toolchain Requirements
--------------------------------
-
-We intend to require newer toolchains as time goes by. This means LLVM's
-codebase can use newer versions of C++ as they get standardized. Requiring newer
-toolchains to build LLVM can be painful for those building LLVM; therefore, it
-will only be done through the following process:
-
- * Generally, try to support LLVM and GCC versions from the last 3 years at a
- minimum. This time-based guideline is not strict: we may support much older
- compilers, or decide to support fewer versions.
-
- * An RFC is sent to the `llvm-dev mailing list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_
-
- - Detail upsides of the version increase (e.g. which newer C++ language or
- library features LLVM should use; avoid miscompiles in particular compiler
- versions, etc).
- - Detail downsides on important platforms (e.g. Ubuntu LTS status).
-
- * Once the RFC reaches consensus, update the CMake toolchain version checks as
- well as the :doc:`getting started<GettingStarted>` guide. We want to
- soft-error when developers compile LLVM. We say "soft-error" because the
- error can be turned into a warning using a CMake flag. This is an important
- step: LLVM still doesn't have code which requires the new toolchains, but it
- soon will. If you compile LLVM but don't read the mailing list, we should
- tell you!
-
- * Ensure that at least one LLVM release has had this soft-error. Not all
- developers compile LLVM top-of-tree. These release-bound developers should
- also be told about upcoming changes.
-
- * Turn the soft-error into a hard-error after said LLVM release has branched.
+Adding an Established Project To the LLVM Monorepo
+--------------------------------------------------
+
+The `LLVM monorepo <https://github.com/llvm/llvm-project>`_ is the centerpoint
+of development in the LLVM world, and has all of the primary LLVM components,
+including the LLVM optimizer and code generators, Clang, LLDB, etc. `Monorepos
+in general <https://en.wikipedia.org/wiki/Monorepo>`_ are great because they
+allow atomic commits to the project, simplify CI, and make it easier for
+subcommunities to collaborate.
+
+That said, the burden to add things to the LLVM monorepo needs to be very high -
+code that is added to this repository is checked out by everyone in the
+community. As such, we hold subprojects to a high bar similar to "official
+targets", they:
+
+ * Must be generally aligned with the mission of the LLVM project to advance
+ compilers, languages, tools, runtimes, etc.
+ * Must conform to all of the policies laid out in this developer policy
+ document, including license, patent, coding standards, and code of conduct.
+ * Must have an active community that maintains the code, including established
+ code owners.
+ * Should have reasonable documentation about how it works, including a high
+ quality README file.
+ * Should have CI to catch breakage within the project itself or due to
+ underlying LLVM dependencies.
+ * Should have code free of issues the community finds contentious, or be on a
+ clear path to resolving them.
+ * Must be proposed through the LLVM RFC process, and have its addition approved
+ by the LLVM community - this ultimately mediates the resolution of the
+ "should" concerns above.
+
+If you have a project that you think would make sense to add to the LLVM
+monorepo, please start an RFC thread on the llvm-dev mailing list to kick off
+the discussion. This process can take some time and iteration - please don’t
+be discouraged or intimidated by that!
+
+If you have an earlier stage project that you think is aligned with LLVM, please
+see the "Incubating New Projects" section.
+
+Incubating New Projects
+-----------------------
- * Update the :doc:`coding standards<CodingStandards>` to allow the new
- features we've explicitly approved in the RFC.
+The burden to add a new project to the LLVM monorepo is intentionally very high,
+but that can have a chilling effect on new and innovative projects. To help
+foster these sorts of projects, LLVM supports an "incubator" process that is
+much easier to get started with. It provides space for potentially valuable,
+new top-level and sub-projects to reach a critical mass before they have enough
+code to prove their utility and grow a community. This also allows
+collaboration between teams that already have permissions to make contributions
+to projects under the LLVM umbrella.
+
+Projects which can be considered for the LLVM incubator meet the following
+criteria:
+
+ * Must be generally aligned with the mission of the LLVM project to advance
+ compilers, languages, tools, runtimes, etc.
+ * Must conform to the license, patent, and code of conduct policies laid out
+ in this developer policy document.
+ * Must have a documented charter and development plan, e.g. in the form of a
+ README file, mission statement, and/or manifesto.
+ * Should conform to coding standards, incremental development process, and
+ other expectations.
+ * Should have a sense of the community that it hopes to eventually foster, and
+ there should be interest from members with different affiliations /
+ organizations.
+ * Should have a feasible path to eventually graduate as a dedicated top-level
+ or sub-project within the `LLVM monorepo
+ <https://github.com/llvm/llvm-project>`_.
+ * Should include a notice (e.g. in the project README or web page) that the
+ project is in ‘incubation status’ and is not included in LLVM releases (see
+ suggested wording below).
+ * Must be proposed through the LLVM RFC process, and have its addition
+ approved by the LLVM community - this ultimately mediates the resolution of
+ the "should" concerns above.
+
+That said, the project need not have any code to get started, and need not have
+an established community at all! Furthermore, incubating projects may pass
+through transient states that violate the "Should" guidelines above, or would
+otherwise make them unsuitable for direct inclusion in the monorepo (e.g.
+dependencies that have not yet been factored appropriately, leveraging
+experimental components or APIs that are not yet upstream, etc).
+
+When approved, the llvm-admin group can grant the new project:
+ * A new repository in the LLVM Github Organization - but not the LLVM monorepo.
+ * New mailing list, discourse forum, and/or discord chat hosted with other LLVM
+ forums.
+ * Other infrastructure integration can be discussed on a case-by-case basis.
+
+Graduation to the mono-repo would follow existing processes and standards for
+becoming a first-class part of the monorepo. Similarly, an incubating project
+may be eventually retired, but no process has been established for that yet. If
+and when this comes up, please start an RFC discussion on llvm-dev.
+
+This process is very new - please expect the details to change, it is always
+safe to ask on the `llvm-dev mailing list
+<https://lists.llvm.org/mailman/listinfo/llvm-dev>`_ about this.
+
+Suggested disclaimer for the project README and the main project web page:
- * Start using the new features in LLVM's codebase.
+::
-Here's a `sample RFC
-<http://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html>`_ and the
-`corresponding change <https://reviews.llvm.org/D57264>`_.
+ This project is participating in the LLVM Incubator process: as such, it is
+ not part of any official LLVM release. While incubation status is not
+ necessarily a reflection of the completeness or stability of the code, it
+ does indicate that the project is not yet endorsed as a component of LLVM.
.. _copyright-license-patents:
projects / platform / upstream / llvm.git / commitdiff