Compatibility report

Given the very large user base of SLF4J, we take backward
compatibility very seriously. As such, changes that may cause
incompatibility problems are listed in this page. Moreover, since
slf4j-api.jar is the main entry point into SLF4J, that is the module
that will be covered in most detail.

Please note that in many cases incompatibility problems are
caused by mixing different versions of slf4j artifacts. For example,
if you are using slf4j-api-1.5.4.jar you should also use
slf4j-simple-1.5.4.jar, using slf4j-simple-1.4.2.jar will not
work. The same goes for all other SLF4J artifacts.

The list is computed using clirr. If you have reasons
to suspect incompatible changes not mentioned here, please kindly
contact the slf4j developers list.

The hasChildren() and other documentation in the
Marker interface was misleading users to think in terms of parent
child relationship for markers. However, as bug 100
illustrates, associating markers as parents and children is not very
helpful. It is much better to think of markers in terms of abstract
graphs. As such, we now say that a marker contains (zero or more)
references to other markers.

This breaking change is justified because it corrects a
conceptual error in the design. Previously, it was all too easy for
developers to get confused and incorrectly link markers
together.

The addition of the getCopyOfContextMap() method in
the MDCAdapter class should only impact users who have
their own implementation of the said interface. Except for bindings
that ship with SLF4J and for logback-classic, which will be
naturally upgraded, there are no known other implementations of
MDCAdapter. In a rare but still possible scenario, if
the user mixes different versions for slf4j-api.jar, say version
1.5.1. and an SLF4J binding, say slf4j-log4j12.jar version 1.5.0,
then a java.lang.AbstractMethodError will be thrown,
but only if the client code calls the newly added method. In short, although generally speaking the
addition of a method to an interface is a breaking change, we are
confident that no users will be impacted in this particular
case.

Similar reasoning applies to the setContextMap(Map)
method.

The addition of getDetachedMarker(String) method in
the org.slf4j.IMarkerFactory should not impact users as
the only (known) implementation of this interface ships with SLF4J
itself.

The equals() and hashCode() methods
were added to the org.slf4j.Marker interface for
documentation purposes. Given that all objects implicitly implement
these methods, their addition should theoretically not break
existing code.