Stay Informed¶

Developers should stay informed by reading theLLVM Discourse forums and subscribingto the categories of interest for notifications.

Paying attention to changes being made by others is a good way to see what other peopleare interested in and watching the flow of the project as a whole.

Contibutions to the project are made throughGitHub Pull Requests.You can subscribe to notification for areas of the codebase by joiningone of thepr-subscribers-*GitHub teams. Thismappingindicates which team is associated with a particular paths in the repository.

You can also subscribe to the “commits” mailing list for a subproject you’re interested in,such asllvm-commits,cfe-commits, orlldb-commits.

Missing features and bugs are tracked through ourGitHub issue trackerand assigned labels. We recommend that active developers monitor incoming issues.You can subscribe for notification for specific components by joiningone of theissue-subscribers-*teams.You may also subscribe to thellvm-bugs email list to keep trackof bugs and enhancements occurring in the entire project. We really appreciate peoplewho are proactive at catching incoming bugs in their components and dealing with thempromptly.

Please be aware that all public LLVM mailing lists and discourse forums are public and archived, andthat notices of confidentiality or non-disclosure cannot be respected.

Making and Submitting a Patch¶

When making a patch for review, the goal is to make it as easy for the reviewerto read it as possible. As such, we recommend that you:

1. Make your patch against git main, not a branch, and not an old versionof LLVM. This makes it easy to apply the patch. For information on how toclone from git, please see theGetting Started Guide.

2. Similarly, patches should be submitted soon after they are generated. Oldpatches may not apply correctly if the underlying code changes between thetime the patch was created and the time it is applied.

3. Once you have created your patch, create aGitHub Pull Request forit (or commit it directly if applicable).

When submitting patches, please do not add confidentiality or non-disclosurenotices to the patches themselves. These notices conflict with the LLVMlicensing terms and may result in your contribution being excluded.

Email Addresses¶

The LLVM project uses email to communicate to contributors outside of theGitHub platform about their past contributions. Primarily, our buildbotinfrastructure uses emails to contact contributors about build and testfailures.

Therefore, the LLVM community requires contributors to have a publicemail address associated with their GitHub commits, so please ensure that “Keepmy email addresses private” is disabled in youraccount settings.

Code Reviews¶

LLVM has a code-review policy. Code review is one way to increase the quality ofsoftware. Please seeLLVM Code-Review Policy and Practices for more information on LLVM’s code-reviewprocess.

Making Potentially Breaking Changes¶

Please help notify users and vendors of potential disruptions when upgrading toa newer version of a tool. For example, deprecating a feature that is expectedto be removed in the future, removing an already-deprecated feature, upgrading adiagnostic from a warning to an error, switching important default behavior, orany other potentially disruptive situation thought to be worth raisingawareness of. For such changes, the following should be done:

• When performing the code review for the change, please add any applicable“vendors” group to the review for their awareness. The purpose of thesegroups is to give vendors early notice that potentially disruptive changesare being considered but have not yet been accepted. Vendors can give earlytesting feedback on the changes to alert us to unacceptable breakages. Thecurrent 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 informationabout the potentially breaking changes to thePotentiallyBreakingChangessection of the project’s release notes. The release note should haveinformation about what the change is, what is potentially disruptive aboutit, as well as any code examples, links, and motivation that is appropriateto share with users. This helps users to learn about potential issues withupgrading to that release.

• After the change has been committed to the repository, the potentiallydisruptive changes described in the release notes should be posted to theAnnouncements channel onDiscourse. The post should be tagged with thepotentially-breaking labeland a label specific to the project (such asclang,llvm, etc). Thisis another mechanism by which we can give pre-release notice to users aboutpotentially disruptive changes. It is a lower-traffic alternative to thejoining “vendors” group. To automatically be notified of new announcementswith thepotentially-breaking label, go to your user preferences page inDiscourse, and add the label to one of the watch categories underNotifications->Tags.

Maintainers¶

The LLVM Project aims to evolve features quickly while continually being in arelease-ready state. In order to accomplish this, the project needs volunteerswilling to do the less glamorous work to ensure we produce robust, high-qualityproducts.

Maintainers are those volunteers; they are regular contributors who volunteerto take on additional community responsibilities beyond code contributions.Community members can find active and inactive maintainers for a project in theMaintainers.rst file at the root directory of the individual project.

Maintainers are volunteering to take on the following shared responsibilitieswithin an area of a project:

• ensure that commits receive high-quality review, either by the maintaineror by someone else,

• help to confirm and comment on issues,

• mediate code review disagreements through collaboration with othermaintainers (and other reviewers) to come to a consensus on how best toproceed with disputed changes,

• actively engage with relevant RFCs,

• aid release managers with backporting and other release-relatedactivities,

• be a point of contact for contributors who need help (answering questionson Discord/Discourse or holding office hours).

Each top-level project in the monorepo will specify one or morelead maintainers who are responsible for ensuring community needs aremet for that project. This role is like any other maintainer role,except the responsibilities span the project rather than a limited areawithin the project. If you cannot reach a maintainer or don’t know whichmaintainer to reach out to, a lead maintainer is always a good choiceto reach out to. If a project has no active lead maintainers, it may be areasonable candidate for removal from the monorepo. A discussion should bestarted on Discourse to find a new, active lead maintainer or whether theproject should be discontinued.

All contributors with commit access to the LLVM Project are eligible to be amaintainer. However, we are looking for people who can commit to:

• engaging in their responsibilities the majority of the days in a month,

• ensuring that they, and the community members they interact with, abide bythe LLVM Community Code of Conduct, and

• performing these duties for at least three months.

We recognize that priorities shift, job changes happen, burnout is real,extended vacations are a blessing, and people’s lives are generally complex.Therefore, we want as little friction as possible for someone to become amaintainer or to step down as a maintainer.

To become a new maintainer, you can volunteer yourself by posting a PR whichadds yourself to the area(s) you are volunteering for. Alternatively, anexisting maintainer can nominate you by posting a PR, but the nominee mustexplicitly accept the PR so that it’s clear they agree to volunteer within theproposed area(s). The PR will be accepted so long as at least one maintainer inthe same project vouches for their ability to perform the responsibilities andthere are no explicit objections raised by the community.

To step down as a maintainer, you can move your name to the “inactivemaintainers” section of theMaintainers.rst file for the project, or removeyour name entirely; no PR review is necessary. Additionally, any maintainer whohas not been actively performing their responsibilities over an extended periodof time can be moved to the “inactive maintainers” section by another activemaintainer within that project with agreement from one other active maintainerwithin that project. If there is only one active maintainer for a project,please post on Discourse to solicit wider community feedback about the removaland future direction for the project. However, please discuss the situationwith the inactive maintainer before such removal to avoid accidentalmiscommunications. If the inactive maintainer is unreachable, no discussionwith them is required. Stepping down or being removed as a maintainer is normaland does not prevent someone from resuming their activities as a maintainer inthe future.

To resume activities as a maintainer, you can post a PR moving your name fromthe “inactive maintainers” section of theMaintainers.rst file to theactive maintainers list. Because the volunteer was already previously accepted,they will be re-accepted so long as at least one maintainer in the same projectapproves the PR and there are no explicit objections raised by the community.

Test Cases¶

Developers are required to create test cases for any bugs fixed and any newfeatures added. Some tips for getting your testcase approved:

• All feature and regression test cases are added to thellvm/testdirectory. The appropriate sub-directory should be selected (see theTesting Guide for details).

• Test cases should be written inLLVM assembly language.

• Test cases, especially for regressions, should be reduced as much as possible,bybugpoint or manually. It is unacceptable to place anentire failing program intollvm/test as this creates atime-to-testburden on all developers. Please keep them short.

• Avoid adding links to resources that are not available to the entirecommunity, such as links to private bug trackers, internal corporatedocumentation, etc. Instead, add sufficient comments to the test to providethe context behind such links.

Note that llvm/test and clang/test are designed for regression and small featuretests only. More extensive test cases (e.g., entire applications, benchmarks,etc) should be added to thellvm-test test suite. The llvm-test suite isfor coverage (correctness, performance, etc) testing, not feature or regressiontesting.

Release Notes¶

Many projects in LLVM communicate important changes to users through releasenotes, typically found indocs/ReleaseNotes.rst for the project. Changes toa project that are user-facing, or that users may wish to know about, should beadded to the project’s release notes at the author’s or code reviewer’sdiscretion, preferably as part of the commit landing the changes. Examples ofchanges that would typically warrant adding a release note (this list is notexhaustive):

• Adding, removing, or modifying command-line options.

• Adding, removing, or regrouping a diagnostic.

• Fixing a bug that potentially has significant user-facing impact (please linkto the issue fixed in the bug database).

• Adding or removing optimizations that have widespread impact or enables newprogramming paradigms.

• Modifying a C stable API.

• Notifying users about a potentially disruptive change expected to be made ina future release, such as removal of a deprecated feature. In this case, therelease note should be added to aPotentiallyBreakingChanges section ofthe notes with sufficient information and examples to demonstrate thepotential disruption. Additionally, any new entries to this section should beannounced in theAnnouncementschannel on Discourse. SeeMaking Potentially Breaking Changes for more details.

Code reviewers are encouraged to request a release note if they think one iswarranted when performing a code review.

Quality¶

The minimum quality standards that any change must satisfy before beingcommitted to the main development branch are:

1. Code must adhere to theLLVM Coding Standards.

2. Code must compile cleanly (no errors, no warnings) on at least one platform.

3. Bug fixes and new features shouldinclude a testcase so we know if thefix/feature ever regresses in the future.

4. Code must pass thellvm/test test suite.

5. The code must not cause regressions on a reasonable subset of llvm-test,where “reasonable” depends on the contributor’s judgement and the scope ofthe change (more invasive changes require more testing). A reasonable subsetmight be something like “llvm-test/MultiSource/Benchmarks”.

6. Ensure that links in source code and test files point to publicly availableresources and are used primarily to add additional information rather thanto supply critical context. The surrounding comments should be sufficientto provide the context behind such links.

Additionally, the committer is responsible for addressing any problems found inthe future that the change is responsible for. For example:

• The code should compile cleanly on all supported platforms.

• The changes should not cause any correctness regressions in thellvm-testsuite and must not cause any major performance regressions.

• The change set should not cause performance or correctness regressions for theLLVM tools.

• The changes should not cause performance or correctness regressions in codecompiled by LLVM on all applicable targets.

• You are expected to address anyGitHub Issues thatresult from your change.

We prefer for this to be handled before submission but understand that it isn’tpossible to test all of this for every submission. Our build bots and nightlytesting infrastructure normally finds these problems. A good rule of thumb isto check the nightly testers for regressions the day after your change. Buildbots will directly email you if a group of commits that included yours caused afailure. You are expected to check the build bot messages to see if they areyour fault and, if so, fix the breakage.

Commits that violate these quality standards (e.g. are very broken) may bereverted. This is necessary when the change blocks other developers from makingprogress. The developer is welcome to re-commit the change after the problem hasbeen fixed.

Commit messages¶

Although we don’t enforce the format of commit messages, we prefer thatyou follow these guidelines to help review, search in logs, email formattingand so on. These guidelines are very similar to rules used by other open sourceprojects.

Most importantly, the contents of the message should be carefully written toconvey the rationale of the change (without delving too much in detail). Italso should avoid being vague or overly specific. For example, “bits were notset right” will leave the reviewer wondering about which bits, and why theyweren’t right, while “Correctly set overflow bits in TargetInfo” conveys almostall there is to the change.

Below are some guidelines about the format of the message itself:

• Separate the commit message into title and body separated by a blank line.

• If you’re not the original author, ensure the ‘Author’ property of the commit isset to the original author and the ‘Committer’ property is set to yourself.You can use a command similar togitcommit--amend--author="JohnDoe<jdoe@llvm.org>" to correct theauthor property if it is incorrect. SeeAttribution of Changes for moreinformation including the method we used for attribution before the projectmigrated to git.

  In the rare situation where there are multiple authors, please use thegittag ‘Co-authored-by:’ to list the additional authors.

• The title should be concise. Because all commits are emailed to the list withthe first line as the subject, long titles are frowned upon. Short titlesalso look better ingit log.

• When the changes are restricted to a specific part of the code (e.g. aback-end or optimization pass), it is customary to add a tag to thebeginning of the line in square brackets. For example, “[SCEV] …”or “[OpenMP] …”. This helps email filters and searches for post-commitreviews.

• The body, if it exists, should be separated from the title by an empty line.

• The body should be concise, but explanatory, including a completereasoning. Unless it is required to understand the change, examples,code snippets and gory details should be left to bug comments, webreview or the mailing list.

• Text formatting and spelling should follow the same rules as documentationand in-code comments, ex. capitalization, full stop, etc.

• If the commit is a bug fix on top of another recently committed patch, or arevert or reapply of a patch, include the git commit hash of the priorrelated commit. This could be as simple as “Revert commit NNNN because itcaused PR#”.

• If the patch has been reviewed, add a link to its review page, as shownhere.If the patch fixes a bug in GitHub Issues, we encourage adding a reference tothe issue being closed, as describedhere.

• It is also acceptable to add other metadata to the commit message to automateprocesses, including for downstream consumers. This metadata can includelinks to resources that are not available to the entire community. However,such links and/or metadata should not be used in place of making the commitmessage self-explanatory. Note that such non-public links should not beincluded in the submitted code.

For minor violations of these recommendations, the community normally favorsreminding the contributor of this policy over reverting. Minor corrections andomissions can be handled by sending a reply to the commits mailing list.

Patch reversion policy¶

As a community, we strongly value having the tip of tree in a good state whileallowing rapid iterative development. As such, we tend to make much heavieruse of reverts to keep the tree healthy than some other open source projects,and our norms are a bit different.

How should you respond if someone reverted your change?

• Remember, it is normal and healthy to have patches reverted. Having a patchreverted does not necessarily mean you did anything wrong.

• We encourage explicitly thanking the person who reverted the patch for doingthe task on your behalf.

• If you need more information to address the problem, please follow up in theoriginal commit thread with the reverting patch author.

When should you revert your own change?

• Any time you learn of a serious problem with a change, you should revert it.We strongly encourage “revert to green” as opposed to “fixing forward”. Weencourage reverting first, investigating offline, and then reapplying thefixed patch - possibly after another round of review if warranted.

• If you break a buildbot in a way which can’t be quickly fixed, please revert.

• If a test case that demonstrates a problem is reported in the commit thread,please revert and investigate offline.

• If you receive substantialpost-commit reviewfeedback, please revert and address said feedback before recommitting.(Possibly after another round of review.)

• If you are asked to revert by another contributor, please revert and discussthe merits of the request offline (unless doing so would further destabilizetip of tree).

When should you revert someone else’s change?

• In general, if the author themselves would revert the change per theseguidelines, we encourage other contributors to do so as a courtesy to theauthor. This is one of the major cases where our norms differ from others;we generally consider reverting a normal part of development. We don’texpect contributors to be always available, and the assurance that aproblematic patch will be reverted and we can return to it at our nextopportunity enables this.

What are the expectations around a revert?

• Use your best judgment. If you’re uncertain, please start an email onthe commit thread asking for assistance. We aren’t trying to enumerateevery case, but rather give a set of guidelines.

• You should be sure that reverting the change improves the stability of tipof tree. Sometimes reverting one change in a series can worsen thingsinstead of improving them. We expect reasonable judgment to ensure thatthe proper patch or set of patches is being reverted.

• The commit message for the reverting commit should explain why patchis being reverted.

• It is customary to respond to the original commit email mentioning therevert. This serves as both a notice to the original author that theirpatch was reverted, and helps others following llvm-commits track context.

• Ideally, you should have a publicly reproducible test case ready to share.Where possible, we encourage sharing of test cases in commit threads, orin PRs. We encourage the reverter to minimize the test case and to prunedependencies where practical. This even applies when reverting your ownpatch; documenting the reasons for others who might be following alongis critical.

• It is not considered reasonable to revert without at least the promise toprovide a means for the patch author to debug the root issue. If a situationarises where a public reproducer can not be shared for some reason (e.g.requires hardware patch author doesn’t have access to, sharp regression incompile time of internal workload, etc.), the reverter is expected to beproactive about working with the patch author to debug and test candidatepatches.

• Reverts should be reasonably timely. A change submitted two hours agocan be reverted without prior discussion. A change submitted two years agoshould not be. Where exactly the transition point is is hard to say, butit’s probably in the handful of days in tree territory. If you are unsure,we encourage you to reply to the commit thread, give the author a bit torespond, and then proceed with the revert if the author doesn’t seem to beactively responding.

• When re-applying a reverted patch, the commit message should be updated toindicate the problem that was addressed and how it was addressed.

Obtaining Commit Access¶

Once you have 3 or more merged pull requests, you may usethis linkto file an issue and request commit access. Replace the <user> string in the titlewith your github username, and explain why you are requesting commit access inthe issue description. Once the issue is created, you will need to get twocurrent contributors to support your request before commit access will be granted.

Reviewers of your committed patches will automatically be CCed upon creating the issue.Most commonly these reviewers will provide the necessary approval, but approvalsfrom other LLVM committers are also acceptable. Those reviewing the application areconfirming that you have indeed had three patches committed, and that based on interactionson those reviews and elsewhere in the LLVM community they have no concern about youadhering to our Developer Policy and Code of Conduct.

If approved, a GitHub invitation will be sent to yourGitHub account. In case you don’t get notification from GitHub, go toInvitation Link directly. Onceyou accept the invitation, you’ll get commit access.

Prior to obtaining commit access, it is common practice to request thatsomeone with commit access commits on your behalf. When doing so, pleaseprovide the name and email address you would like to use in the Authorproperty of the commit.

For external tracking purposes, committed changes are automatically reflectedon a commits mailing list soon after the commit lands (e.g.llvm-commits).Note that these mailing lists are moderated, and it is not unusual for a largecommit to require a moderator to approve the email, so do not be concerned if acommit does not immediately appear in the archives.

If you have recently been granted commit access, these policies apply:

1. You are grantedcommit-after-approval to all parts of LLVM. Forinformation on how to get approval for a patch, please seeLLVM Code-Review Policy and Practices.When approved, you may commit it yourself.

2. You are allowed to commit patches without approval which you think areobvious. This is clearly a subjective decision — we simply expect you touse good judgement. Examples include: fixing build breakage, revertingobviously broken patches, documentation/comment changes, any other minorchanges. Avoid committing formatting- or whitespace-only changes outside ofcode you plan to make subsequent changes to. Also, try to separateformatting or whitespace changes from functional changes, either bycorrecting the format first (ideally) or afterward. Such changes should behighly localized and the commit message should clearly state that the commitis not intended to change functionality, usually by stating it isNFC.

3. You are allowed to commit patches without approval to those portions of LLVMthat you have contributed or maintain (i.e., have been assignedresponsibility for), with the proviso that such commits must not break thebuild. This is a “trust but verify” policy, and commits of this nature arereviewed after they are committed.

4. Multiple violations of these policies or a single egregious violation maycause commit access to be revoked.

In any case, your changes are still subject tocode review (either before orafter they are committed, depending on the nature of the change). You areencouraged to review other peoples’ patches as well, but you aren’t requiredto do so.

Making a Major Change¶

When a developer begins a major new project with the aim of contributing it backto LLVM, they should inform the community with a post to theLLVM Discourse forums, to the extentpossible. The reason for this is to:

1. keep the community informed about future changes to LLVM,

2. avoid duplication of effort by preventing multiple parties working on thesame thing and not knowing about it, and

3. ensure that any technical issues around the proposed work are discussed andresolved before any significant work is done.

The design of LLVM is carefully controlled to ensure that all the pieces fittogether well and are as consistent as possible. If you plan to make a majorchange to the way LLVM works or want to add a major new extension, it is a goodidea to get consensus with the development community before you start working onit.

Once the design of the new feature is finalized, the work itself should be doneas a series ofincremental changes, not as a long-term development branch.

Incremental Development¶

In the LLVM project, we do all significant changes as a series of incrementalpatches. We have a strong dislike for huge changes or long-term developmentbranches. Long-term development branches have a number of drawbacks:

1. Branches must have mainline merged into them periodically. If the branchdevelopment and mainline development occur in the same pieces of code,resolving merge conflicts can take a lot of time.

2. Other people in the community tend to ignore work on branches.

3. Huge changes (produced when a branch is merged back onto mainline) areextremely difficult tocode review.

4. Branches are not routinely tested by our nightly tester infrastructure.

5. Changes developed as monolithic large changes often don’t work until theentire set of changes is done. Breaking it down into a set of smallerchanges increases the odds that any of the work will be committed to the mainrepository.

To address these problems, LLVM uses an incremental development style and werequire contributors to follow this practice when making a large/invasivechange. Some tips:

• Large/invasive changes usually have a number of secondary changes that arerequired before the big change can be made (e.g. API cleanup, etc). Thesesorts of changes can often be done before the major change is done,independently of that work.

• The remaining inter-related work should be decomposed into unrelated sets ofchanges if possible. Once this is done, define the first increment and getconsensus on what the end goal of the change is.

• Each change in the set can be stand alone (e.g. to fix a bug), or part of aplanned series of changes that works towards the development goal.

• Each change should be kept as small as possible. This simplifies your work(into a logical progression), simplifies code review and reduces the chancethat you will get negative feedback on the change. Small increments alsofacilitate the maintenance of a high quality code base.

• Often, an independent precursor to a big change is to add a new API and slowlymigrate clients to use the new API. Each change to use the new API is often“obvious” and can be committed without review. Once the new API is in placeand used, it is much easier to replace the underlying implementation of theAPI. This implementation change is logically separate from the APIchange.

If you are interested in making a large change, and this scares you, please makesure to firstdiscuss the change/gather consensus then ask about the best wayto go about making the change.

Attribution of Changes¶

When contributors submit a patch to an LLVM project, other developers withcommit access may commit it for the author once appropriate (based on theprogression of code review, etc.). When doing so, it is important to retaincorrect attribution of contributions to their contributors. However, we do notwant the source code to be littered with random attributions “this code writtenby J. Random Hacker” (this is noisy and distracting). In practice, the revisioncontrol system keeps a perfect history of who changed what, and the CREDITS.txtfile describes higher-level contributions. If you commit a patch for someoneelse, please follow the attribution of changes in the simple manner as outlinedby thecommit messages section. Overall, please do not add contributor namesto the source code.

Also, don’t commit patches authored by others unless they have submitted thepatch to the project or you have been authorized to submit them on their behalf(you work together and your company authorized you to contribute the patches,etc.). The author should first submit them to the relevant project’s commitlist, development list, or LLVM bug tracker component. If someone sends youa patch privately, encourage them to submit it to the appropriate list first.

Our previous version control system (subversion) did not distinguish between theauthor and the committer like git does. As such, older commits used a differentattribution mechanism. The previous method was to include “Patch by John Doe.”in a separate line of the commit message and there are automated processes thatrely on this format.

Bans¶

The goal of a ban is to protect people in the community from having to interactwith people who are consistently not respecting theLLVM Community Code of Conduct in LLVM project spaces. Contributions ofany variety (pull requests, issue reports, forum posts, etc.) requireinteracting with the community. Therefore, we do not accept any form of directcontribution from a banned individual.

Indirect contributions are permissible only by someone taking full ownership ofsuch a contribution and they are responsible for all related interactions withthe community regarding that contribution.

When in doubt how to act in a specific instance, please reach out toconduct@llvm.org for advice.

IR Backwards Compatibility¶

When the IR format has to be changed, keep in mind that we try to maintain somebackwards compatibility. The rules are intended as a balance between conveniencefor llvm users and not imposing a big burden on llvm developers:

• The textual format is not backwards compatible. We don’t change it too often,but there are no specific promises.

• Additions and changes to the IR should be reflected intest/Bitcode/compatibility.ll.

• The current LLVM version supports loading any bitcode since version 3.0.

• After each X.Y release,compatibility.ll must be copied tocompatibility-X.Y.ll. The corresponding bitcode file should be assembledusing the X.Y build and committed ascompatibility-X.Y.ll.bc.

• Newer releases can ignore features from older releases, but they cannotmiscompile them. For example, if nsw is ever replaced with something else,dropping it would be a valid way to upgrade the IR.

• Debug metadata is special in that it is currently dropped during upgrades.

• Non-debug metadata is defined to be safe to drop, so a valid way to upgradeit is to drop it. That is not very user friendly and a bit more effort isexpected, but no promises are made.

C API Changes¶

• Stability Guarantees: The C API is, in general, a “best effort” for stability.This means that we make every attempt to keep the C API stable, but thatstability will be limited by the abstractness of the interface and thestability of the C++ API that it wraps. In practice, this means that thingslike “create debug info” or “create this type of instruction” are likely to beless stable than “take this IR file and JIT it for my current machine”.

• Release stability: We won’t break the C API on the release branch with patchesthat go on that branch, with the exception that we will fix an unintentionalC API break that will keep the release consistent with both the previous andnext release.

• Testing: Patches to the C API are expected to come with tests just like anyother patch.

• Including new things into the API: If an LLVM subcomponent has a C API alreadyincluded, then expanding that C API is acceptable. Adding C API forsubcomponents that don’t currently have one needs to be discussed on theLLVM Discourse forums for design and maintainability feedback prior to implementation.

• Documentation: Any changes to the C API are required to be documented in therelease notes so that it’s clear to external users who do not follow theproject how the C API is changing and evolving.

Updating Toolchain Requirements¶

We intend to require newer toolchains as time goes by. This means LLVM’scodebase can use newer versions of C++ as they get standardized. Requiring newertoolchains to build LLVM can be painful for those building LLVM; therefore, itwill only be done through the following process:

• It is a general goal to support LLVM and GCC versions from the last 3 yearsat a minimum. This time-based guideline is not strict: we may support mucholder compilers, or decide to support fewer versions.

• An RFC is sent to theLLVM Discourse forums

  • Detail upsides of the version increase (e.g. which newer C++ language orlibrary features LLVM should use; avoid miscompiles in particular compilerversions, etc).

  • Detail downsides on important platforms (e.g. Ubuntu LTS status).

• Once the RFC reaches consensus, update the CMake toolchain version checks aswell as thegetting started guide. This provides asofter transition path for developers compiling LLVM, because theerror can be turned into a warning using a CMake flag. This is an importantstep: LLVM still doesn’t have code which requires the new toolchains, but itsoon will. If you compile LLVM but don’t read the forums, we shouldtell you!

• Ensure that at least one LLVM release has had this soft-error. Not alldevelopers compile LLVM top-of-tree. These release-bound developers shouldalso be told about upcoming changes.

• Turn the soft-error into a hard-error after said LLVM release has branched.

• Update thecoding standards to allow the newfeatures we’ve explicitly approved in the RFC.

• Start using the new features in LLVM’s codebase.

Here’s asample RFC and thecorresponding change.

Working with the CI system¶

The main continuous integration (CI) tool for the LLVM project is theLLVM Buildbot. It uses differentbuildersto cover a wide variety of sub-projects and configurations. The builds areexecuted on differentworkers. Builders and workers are configured andprovided by community members.

The Buildbot tracks the commits on the main branch and the release branches.This means that patches are built and tested after they are merged to the thesebranches (aka post-merge testing). This also means it’s okay to break the buildoccasionally, as it’s unreasonable to expect contributors to build and testtheir patch with every possible configuration.

If your commit broke the build:

• Fix the build as soon as possible as this might block other contributors ordownstream users.

• If you need more time to analyze and fix the bug, please revert your change tounblock others.

If someone else broke the build and this blocks your work

• Comment on the code review inGitHub(if available) or email the author, explain the problem and how this impactsyou. Add a link to the broken build and the error message so folks canunderstand the problem.

• Revert the commit if this blocks your work, seerevert_policy .

If a build/worker is permanently broken

• 1st step: contact the owner of the worker. You can find the name and contactinformation for theAdmin of worker on the page of the build in theWorker tab:

  

• 2nd step: If the owner does not respond or fix the worker, please escalateto Galina Kostanova, the maintainer of the BuildBot master.

• 3rd step: If Galina could not help you, please escalate to theInfrastructure Working Group.

Adding a New Target¶

LLVM is very receptive to new targets, even experimental ones, but a number ofproblems can appear when adding new large portions of code, and back-ends arenormally added in bulk. New targets need the same level of support as othercore parts of the compiler, so they are covered in thecore tier of oursupport policy.

We have found that landing large pieces of new code and then trying to fixemergent problems in-tree is problematic for a variety of reasons. For thesereasons, new targets arealways added asexperimental until they can beproven stable, and later moved to non-experimental.

The differences between both classes are:

• Experimental targets are not built by default (they need to be explicitlyenabled at CMake time).

• Test failures, bugs, and build breakages that only appear when theexperimental target is enabled, caused by changes unrelated to the target, arethe responsibility of the community behind the target to fix.

The basic rules for a back-end to be upstreamed inexperimental mode are:

• Every target must have at least onemaintainer. TheMaintainers.rst file has to be updated as part of the first merge. Thesemaintainers make sure that changes to the target get reviewed and steers theoverall effort.

• There must be an active community behind the target. This communitywill help maintain the target by providing buildbots, fixingbugs, answering the LLVM community’s questions and making sure the newtarget doesn’t break any of the other targets, or generic code. Thisbehavior is expected to continue throughout the lifetime of thetarget’s code.

• The code must be free of contentious issues, for example, largechanges in how the IR behaves or should be formed by the front-ends,unless agreed by the majority of the community via refactoring of the(IR standard)before the merge of the new target changes,following theIR Backwards Compatibility.

• The code conforms to all of the policies laid out in this developer policydocument, including license, patent, and coding standards.

• The target should have either reasonable documentation on how itworks (ISA, ABI, etc.) or a publicly available simulator/hardware(either free or cheap enough) - preferably both. This allowsdevelopers to validate assumptions, understand constraints and review codethat can affect the target.

In addition, the rules for a back-end to be promoted toofficial are:

• The target must have addressed every other minimum requirement andhave been stable in tree for at least 3 months. This cool downperiod is to make sure that the back-end and the target community canendure continuous upstream development for the foreseeable future.

• The target’s code must have been completely adapted to this policyas well as thecoding standards. Any exceptions thatwere made to move into experimental mode must have been fixedbeforebecoming official.

• The test coverage needs to be broad and well written (small tests,well documented). The build targetcheck-all must pass with thenew target built, and where applicable, thetest-suite must alsopass without errors, in at least one configuration (publiclydemonstrated, for example, via buildbots).

• Public buildbots need to be created and actively maintained, unlessthe target requires no additional buildbots (ex.check-all coversall tests). The more relevant and public the new target’s CI infrastructureis, the more the LLVM community will embrace it.

Tocontinue as a supported and official target:

• The maintainer(s) must continue following these rules throughout the lifetimeof the target. Continuous violations of aforementioned rules and policiescould lead to complete removal of the target from the code base.

• Degradation in support, documentation or test coverage will make the target asnuisance to other targets and be considered a candidate for deprecation andultimately removed.

In essence, these rules are necessary for targets to gain and retain theirstatus, but also markers to define bit-rot, and will be used to clean up thetree from unmaintained targets.

Those wishing to add a new target to LLVM must follow the procedure below:

1. Read this section and make sure your target follows all requirements. Forminor issues, your community will be responsible for making all necessaryadjustments soon after the initial merge.

2. Send a request for comment (RFC) to theLLVM Discourse forums describingyour target and how it follows all the requirements and what work has beendone and will need to be done to accommodate the official target requirements.Make sure to expose any and all controversial issues, changes needed in thebase code, table gen, etc.

3. Once the response is positive, the LLVM community can start reviewing theactual patches (but they can be prepared before, to support the RFC). Createa sequence of N patches, numbered ‘1/N’ to ‘N/N’ (make sure N is an actualnumber, not the letter ‘N’), that completes the basic structure of the target.

4. The initial patch should add documentation, maintainers, and triple support inclang and LLVM. The following patches add TableGen infrastructure to describethe target and lower instructions to assembly. The final patch must show thatthe target can lower correctly with extensive LIT tests (IR to MIR, MIR toASM, etc).

5. Some patches may be approved before others, but only afterall patches areapproved that the whole set can be merged in one go. This is to guaranteethat all changes are good as a single block.

6. After the initial merge, the target community can stop numbering patches andstart working asynchronously on the target to complete support. They shouldstill seek review from those who helped them in the initial phase, to makesure the progress is still consistent.

7. Once all official requirements have been fulfilled (as above), the maintainersshould request the target to be enabled by default by sending another RFC totheLLVM Discourse forums.

Adding an Established Project To the LLVM Monorepo¶

TheLLVM monorepo is the centerpointof development in the LLVM world, and has all of the primary LLVM components,including the LLVM optimizer and code generators, Clang, LLDB, etc.Monoreposin general are great because theyallow atomic commits to the project, simplify CI, and make it easier forsubcommunities to collaborate.

Like new targets, most projects already in the monorepo are considered to be inthecore tier of oursupport policy. The burden to addthings to the LLVM monorepo needs to be very high - code that is added to thisrepository is checked out by everyone in the community. As such, we holdcomponents to a high bar similar to “official targets”, they:

• Must be generally aligned with the mission of the LLVM project to advancecompilers, languages, tools, runtimes, etc.

• Must conform to all of the policies laid out in this developer policydocument, including license, patent, coding standards, and code of conduct.

• Must have an active community that maintains the code, including establishedmaintainers.

• Should have reasonable documentation about how it works, including a highquality README file.

• Should have CI to catch breakage within the project itself or due tounderlying LLVM dependencies.

• Should have code free of issues the community finds contentious, or be on aclear path to resolving them.

• Must be proposed through the LLVM RFC process, and have its addition approvedby 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 LLVMmonorepo, please start an RFC topic on theLLVM Discourse forums to kick offthe discussion. This process can take some time and iteration - please don’tbe discouraged or intimidated by that!

If you have an earlier stage project that you think is aligned with LLVM, pleasesee the “Incubating New Projects” section.

Incubating New Projects¶

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 helpfoster these sorts of projects, LLVM supports an “incubator” process that ismuch 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 enoughcode to prove their utility and grow a community. This also allowscollaboration between teams that already have permissions to make contributionsto projects under the LLVM umbrella.

Projects which can be considered for the LLVM incubator meet the followingcriteria:

• Must be generally aligned with the mission of the LLVM project to advancecompilers, languages, tools, runtimes, etc.

• Must conform to the license, patent, and code of conduct policies laid outin this developer policy document.

• Must have a documented charter and development plan, e.g. in the form of aREADME file, mission statement, and/or manifesto.

• Should conform to coding standards, incremental development process, andother expectations.

• Should have a sense of the community that it hopes to eventually foster, andthere should be interest from members with different affiliations /organizations.

• Should have a feasible path to eventually graduate as a dedicated top-levelor sub-project within theLLVM monorepo.

• Should include a notice (e.g. in the project README or web page) that theproject is in ‘incubation status’ and is not included in LLVM releases (seesuggested wording below).

• Must be proposed through the LLVM RFC process, and have its additionapproved by the LLVM community - this ultimately mediates the resolution ofthe “should” concerns above.

That said, the project need not have any code to get started, and need not havean established community at all! Furthermore, incubating projects may passthrough transient states that violate the “Should” guidelines above, or wouldotherwise make them unsuitable for direct inclusion in the monorepo (e.g.dependencies that have not yet been factored appropriately, leveragingexperimental 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 LLVMforums.

• Other infrastructure integration can be discussed on a case-by-case basis.

Graduation to the mono-repo would follow existing processes and standards forbecoming a first-class part of the monorepo. Similarly, an incubating projectmay be eventually retired, but no process has been established for that yet. Ifand when this comes up, please start an RFC discussion on theLLVM Discourse forums.

This process is very new - please expect the details to change, it is alwayssafe to ask on theLLVM Discourse forums about this.

Suggested disclaimer for the project README and the main project web page:

ThisprojectisparticipatingintheLLVMIncubatorprocess:assuch,itisnotpartofanyofficialLLVMrelease.Whileincubationstatusisnotnecessarilyareflectionofthecompletenessorstabilityofthecode,itdoesindicatethattheprojectisnotyetendorsedasacomponentofLLVM.

Copyright¶

The LLVM project does not collect copyright assignments, which means that thecopyright for the code in the project is held by the respective contributors.Because you (or your company)retain ownership of the code you contribute, you know it may only be used underthe terms of the open source license you contributed it under: the license foryour contributions cannot be changed in the future without your approval.

Because the LLVM project does not require copyright assignments, changing theLLVM license requires tracking down thecontributors to LLVM and getting them to agree that a license change isacceptable for their contributions. We feel that a high burden for relicensingis good for the project, because contributors do not have to fear that theircode will be used in a way with which they disagree.

Relicensing¶

The last paragraph notwithstanding, the LLVM Project is in the middle of a largeeffort to change licenses, which aims to solve several problems:

• The old licenses made it difficult to move code from (e.g.) the compiler toruntime libraries, because runtime libraries used a different license from therest of the compiler.

• Some contributions were not submitted to LLVM due to concerns thatthe patent grant required by the project was overly broad.

• The patent grant was unique to the LLVM Project, not written by a lawyer, andwas difficult to determine what protection was provided (if any).

The scope of relicensing is all code that is considered part of the LLVMproject, including the main LLVM repository, runtime libraries (compiler_rt,OpenMP, etc), Polly, and all other subprojects. There are a few exceptions:

• Code imported from other projects (e.g. Google Test, Autoconf, etc) willremain as it is. This code isn’t developed as part of the LLVM project, itis used by LLVM.

• Some subprojects are impractical or uninteresting to relicense (e.g. llvm-gccand dragonegg). These will be split off from the LLVM project (e.g. toseparate GitHub projects), allowing interested people to continue theirdevelopment elsewhere.

To relicense LLVM, we will be seeking approval from all of the copyright holdersof code in the repository, or potentially remove/rewrite code if we cannot.This is a largeand challenging project which will take a significant amount of time tocomplete.

Starting on 2024-06-01 (first of June 2024), new contributions only need tobe covered by the new LLVM license, i.e. Apache-2.0 WITH LLVM-exception.Before this date, the project required all contributions to be made underboth the new license and the legacy license.

If you are a contributor to LLVM with contributions committed before 2019-01-19and have not done so already, please do follow the instructions athttps://foundation.llvm.org/docs/relicensing/, under section “IndividualRelicensing Agreement” to relicense your contributions under the new license.

New LLVM Project License Framework¶

Contributions to LLVM are licensed under theApache License, Version 2.0, with two limitedexceptions intended to ensure that LLVM is very permissively licensed.Collectively, the name of this license is “Apache 2.0 License with LLVMexceptions”. The exceptions read:

----LLVMExceptionstotheApache2.0License----Asanexception,if,asaresultofyourcompilingyoursourcecode,portionsofthisSoftwareareembeddedintoanObjectformofsuchsourcecode,youmayredistributesuchembeddedportionsinsuchObjectformwithoutcomplyingwiththeconditionsofSections4(a),4(b)and4(d)oftheLicense.Inaddition,ifyoucombineorlinkcompiledformsofthisSoftwarewithsoftwarethatislicensedundertheGPLv2("Combined Software")andifacourtofcompetentjurisdictiondeterminesthatthepatentprovision(Section3),theindemnityprovision(Section9)orotherSectionoftheLicenseconflictswiththeconditionsoftheGPLv2,youmayretroactivelyandprospectivelychoosetodeemwaivedorotherwiseexcludesuchSection(s)oftheLicense,butonlyintheirentiretyandonlywithrespecttotheCombinedSoftware.

We intend to keep LLVM perpetually open source and available under a permissivelicense - this fosters the widest adoption of LLVM byallowing commercial products to be derived from LLVM with few restrictionsand without a requirement for making any derived works also open source. Inparticular, LLVM’s license is not a “copyleft” license like the GPL.

The “Apache 2.0 License with LLVM exceptions” allows you to:

• freely download and use LLVM (in whole or in part) for personal, internal, orcommercial purposes.

• include LLVM in packages or distributions you create.

• combine LLVM with code licensed under every other major open sourcelicense (including BSD, MIT, GPLv2, GPLv3…).

• make changes to LLVM code without being required to contribute it backto the project - contributions are appreciated though!

However, it imposes these limitations on you:

• You must retain the copyright notice if you redistribute LLVM: You cannotstrip the copyright headers off or replace them with your own.

• Binaries that include LLVM must reproduce the copyright notice (e.g. in anincluded README file or in an “About” box), unless the LLVM code was added asa by-product of compilation. For example, if an LLVM runtime library likecompiler_rt or libc++ was automatically included into your application by thecompiler, you do not need to attribute it.

• You can’t use our names to promote your products (LLVM derived or not) -though you can make truthful statements about your use of the LLVM code,without implying our sponsorship.

• There’s no warranty on LLVM at all.

We want LLVM code to be widely used, and believe that this provides a model thatis great for contributors and users of the project. For more information aboutthe Apache 2.0 License, please see theApache License FAQ, maintained by theApache Project.

Patents¶

Section 3 of the Apache 2.0 license is a patent grant under whichcontributors of code to the project contribute the rights to use any oftheir patents that would otherwise be infringed by that code contribution(protecting uses of that code). Further, the patent grant is revokedfrom anyone who files a patent lawsuit about code in LLVM - this protects thecommunity by providing a “patent commons” for the code base and reducing theodds of patent lawsuits in general.

The license specifically scopes which patents are included with codecontributions. To help explain this, theApache License FAQ explains this scope usingsome questions and answers, which we reproduce here for your convenience (forreference, the “ASF” is the Apache Software Foundation, the guidance stillholds though):

Q1: If I own a patent and contribute to a Work, and, at the time mycontribution is included in that Work, none of my patent's claims are subjectto Apache's Grant of Patent License, is there a way any of those claims wouldlater become subject to the Grant of Patent License solely due to subsequentcontributions by other parties who are not licensees of that patent.A1: No.Q2: If at any time after my contribution, I am able to license other patentclaims that would have been subject to Apache's Grant of Patent License ifthey were licensable by me at the time of my contribution, do those otherclaims become subject to the Grant of Patent License?A2: Yes.Q3: If I own or control a licensable patent and contribute code to a specificApache product, which of my patent claims are subject to Apache's Grant ofPatent License?A3:  The only patent claims that are licensed to the ASF are those you own orhave the right to license that read on your contribution or on thecombination of your contribution with the specific Apache product to whichyou contributed as it existed at the time of your contribution. No additionalpatent claims become licensed as a result of subsequent combinations of yourcontribution with any other software. Note, however, that licensable patentclaims include those that you acquire in the future, as long as they read onyour original contribution as made at the original time. Once a patent claimis subject to Apache's Grant of Patent License, it is licensed under theterms of that Grant to the ASF and to recipients of any software distributedby the ASF for any Apache software product whatsoever.

Legacy License Structure¶

We intend to keep LLVM perpetually open source and to use a permissive opensource license. The code inLLVM is available under theUniversity of Illinois/NCSA Open Source License, which boils down tothis:

• You can freely distribute LLVM.

• You must retain the copyright notice if you redistribute LLVM.

• Binaries derived from LLVM must reproduce the copyright notice (e.g. in anincluded README file).

• You can’t use our names to promote your LLVM derived products.

• There’s no warranty on LLVM at all.

We believe this fosters the widest adoption of LLVM because itallowscommercial products to be derived from LLVM with few restrictions and withouta requirement for making any derived works also open source (i.e. LLVM’slicense is not a “copyleft” license like the GPL). We suggest that you read theLicense if furtherclarification is needed.

In addition to the UIUC license, the runtime library components of LLVM(compiler_rt, libc++, and libclc) are also licensed under theMIT License, which does not containthe binary redistribution clause. As a user of these runtime libraries, itmeans that you can choose to use the code under either license (and thus don’tneed the binary redistribution clause), and as a contributor to the code thatyou agree that any contributions to these libraries be licensed under bothlicenses. We feel that this is important for runtime libraries, because theyare implicitly linked into applications and therefore should not subject thoseapplications to the binary redistribution clause. This also means that it is okto move code from (e.g.) libc++ to the LLVM core without concern, but that codecannot be moved from the LLVM core to libc++ without the copyright owner’spermission.

AI generated contributions¶

Artificial intelligence systems raise many questions around copyright that haveyet to be answered. Our policy on AI tools is guided by our copyright policy:Contributors are responsible for ensuring that they have the right to contributecode under the terms of our license, typically meaning that either they, theiremployer, or their collaborators hold the copyright. Using AI tools toregenerate copyrighted material does not remove the copyright, and contributorsare responsible for ensuring that such material does not appear in theircontributions.

As such, the LLVM policy is that contributors are permitted to use artificialintelligence tools to produce contributions, provided that they have the rightto license that code under the project license. Contributions found to violatethis policy will be removed just like any other offending contribution.

While the LLVM project has a liberal policy on AI tool use, contributors areconsidered responsible for their contributions. We encourage contributors toreview all generated code before sending it for review to verify itscorrectness and to understand it so that they can answer questions during codereview. Reviewing and maintaining generated code that the original contributordoes not understand is not a good use of limited project resources.