progress. The developer is welcome to re-commit the change after the problem has
been fixed.
+.. _commit messages:
+
+Commit messages
+---------------
+
+Although we don't enforce the format of commit messages, we prefer that
+you follow these guidelines to help review, search in logs, email formatting
+and so on. These guidelines are very similar to rules used by other open source
+projects.
+
+Most importantly, the contents of the message should be carefully written to
+convey the rationale of the change (without delving too much in detail). It
+also should avoid being vague or overly specific. For example, "bits were not
+set right" will leave the reviewer wondering about which bits, and why they
+weren't right, while "Correctly set overflow bits in TargetInfo" conveys almost
+all there is to the change.
+
+Below are some guidelines about the format of the message itself:
+
+* Separate the commit message into title, body and, if you're not the original
+ author, a "Patch by" attribution line (see below).
+
+* The title should be concise. Because all commits are emailed to the list with
+ the first line as the subject, long titles are frowned upon. Short titles
+ also look better in `git log`.
+
+* When the changes are restricted to a specific part of the code (e.g. a
+ back-end or optimization pass), it is customary to add a tag to the
+ beginning of the line in square brackets. For example, "[SCEV] ..."
+ or "[OpenMP] ...". This helps email filters and searches for post-commit
+ reviews.
+
+* The body, if it exists, should be separated from the title by an empty line.
+
+* The body should be concise, but explanatory, including a complete
+ reasoning. Unless it is required to understand the change, examples,
+ code snippets and gory details should be left to bug comments, web
+ review or the mailing list.
+
+* If the patch fixes a bug in bugzilla, please include the PR# in the message.
+
+* `Attribution of Changes`_ should be in a separate line, after the end of
+ the body, as simple as "Patch by John Doe.". This is how we officially
+ handle attribution, and there are automated processes that rely on this
+ format.
+
+* Text formatting and spelling should follow the same rules as documentation
+ and in-code comments, ex. capitalization, full stop, etc.
+
+For minor violations of these recommendations, the community normally favors
+reminding the contributor of this policy over reverting. Minor corrections and
+omissions can be handled by sending a reply to the commits mailing list.
+
Obtaining Commit Access
-----------------------
by J. Random Hacker" (this is noisy and distracting). In practice, the revision
control system keeps a perfect history of who changed what, and the CREDITS.txt
file describes higher-level contributions. If you commit a patch for someone
-else, please say "patch contributed by J. Random Hacker!" in the commit
-message. Overall, please do not add contributor names to the source code.
+else, please follow the attribution of changes in the simple manner as outlined
+by the `commit messages`_ section. Overall, please do not add contributor names
+to the source code.
Also, don't commit patches authored by others unless they have submitted the
patch to the project or you have been authorized to submit them on their behalf
a patch privately, encourage them to submit it to the appropriate list first.
+IR Backwards Compatibility
+--------------------------
+
+When the IR format has to be changed, keep in mind that we try to maintain some
+backwards compatibility. The rules are intended as a balance between convenience
+for 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.
+
+* The bitcode format produced by a X.Y release will be readable by all following
+ X.Z releases and the (X+1).0 release.
+
+* Newer releases can ignore features from older releases, but they cannot
+ miscompile 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 upgrade
+ it is to drop it. That is not very user friendly and a bit more effort is
+ expected, but no promises are made.
+
.. _copyright-license-patents:
Copyright, License, and Patents
projects / oota-llvm.git / blobdiff