Merge pull request #8030 from ethereum/docs-non-language-breaking

[docs] Non-language related breaking changes

docs/060-breaking-changes.rst

@@ -98,6 +98,50 @@ or at least were more difficult to achieve prior to Solidity 0.6.0.
    ``x`` must be of type ``address``.
 
 
+Interface Changes
+=================
+
+This section lists changes that are unrelated to the language itself, but that have an effect on the interfaces of
+the compiler. These may change the way how you use the compiler on the command line, how you use its programmable
+interface or how you analyze the output produced by it.
+
+New Error Reporter
+~~~~~~~~~~~~~~~~~~
+
+A new error reporter was introduced, which aims at producing more accessible error messages on the command line.
+It is enabled by default, but passing ``--old-reporter`` falls back to the the deprecated old error reporter.
+
+Metadata Hash Options
+~~~~~~~~~~~~~~~~~~~~~
+
+The compiler now appends the `IPFS <https://ipfs.io/>`_ hash of the metadata file to the end of the bytecode by default
+(for details, see documentation on :doc:`contract metadata <metadata>`). Before 0.6.0, the compiler appended the
+`Swarm <https://ethersphere.github.io/swarm-home/>`_ hash by default, and in order to still support this behaviour,
+the new command line option ``--metadata-hash`` was introduced. It allows you to select the hash to be produced and
+appended, by passing either ``ipfs`` or ``swarm`` as value to the ``--metadata-hash`` command line option.
+Passing the value ``none`` completely removes the hash.
+
+These changes can also be used via the :ref:`Standard JSON Interface<compiler-api>` and effect the metadata JSON generated by the compiler.
+
+The recommended way to read the metadata is to read the last two bytes to determine the length of the CBOR encoding
+and perform a proper decoding on that data block as explained in the :ref:`metadata section<encoding-of-the-metadata-hash-in-the-bytecode>`.
+
+Yul Optimizer
+~~~~~~~~~~~~~
+
+Together with the legacy bytecode optimizer, the :doc:`Yul <yul>` optimizer is now enabled by default when you call the compiler
+with ``--optimize``. It can be disabled by calling the compiler with ``--no-optimize-yul``.
+This mostly affects code that uses ABIEncoderV2.
+
+C API Changes
+~~~~~~~~~~~~~
+
+The client code that uses the C API of ``libsolc`` is now in control of the memory used by the compiler. To make
+this change consistent, ``solidity_free`` was renamed to ``solidity_reset``, the functions ``solidity_alloc`` and
+``solidity_free`` were added and ``solidity_compile`` now returns a string that must be explicitly freed via
+``solidity_free()``.
+
+
 How to update your code
 =======================
 

docs/metadata.rst

@@ -126,6 +126,8 @@ explanatory purposes.
     Starting from Solidity version 0.5.12, though, the array maintains a certain
     order.
 
+.. _encoding-of-the-metadata-hash-in-the-bytecode:
+
 Encoding of the Metadata Hash in the Bytecode
 =============================================