Add documentation about deprecation process

Cf. JuliaLang#10612

base/deprecated.jl

@@ -1,4 +1,22 @@
 # This file is a part of Julia. License is MIT: http://julialang.org/license
+#
+# Deprecated functions and objects
+#
+# Please add new deprecations at the bottom of the file.
+# A function deprecated in a release will be removed in the next one.
+# Please also add a reference to the pull request which introduced the
+# deprecation.
+#
+# For simple cases where a direct replacement is available, use @deprecate:
+# the first argument is the signature of the deprecated method, the second one
+# is the call which replaces it. Remove the definition of the deprecated method
+# and unexport it, as @deprecate takes care of calling the replacement
+# and of exporting the function.
+#
+# For more complex cases, move the body of the deprecated method in this file,
+# and call depwarn() directly from inside it. The symbol depwarn() expects is
+# the name of the function, which is used to ensure that the deprecation warning
+# is only printed the first time for each call place.
 
 macro deprecate(old,new)
     meta = Expr(:meta, :noinline)