Deprecate Keyword.replace/3 and Map.replace/3

`replace!` was introduced to mirror `update!` but without the
anonymous function. Given there is no `update`, we should not
introduce a `replace` until we are sure of the semantics we
want for update.

CHANGELOG.md

@@ -68,6 +68,8 @@
 #### Elixir
 
   * [Enum] `Enum.partition/2` is deprecated in favor of `Enum.split_with/2`
+  * [Keyword] `Keyword.replace/3` is deprecated in favor of `Keyword.fetch/2` and `Keyword.put/3`
+  * [Map] `Map.replace/3` is deprecated in favor of `Map.fetch/2` and `Map.put/3`
 
 ## v1.5
 

lib/elixir/lib/keyword.ex

@@ -594,23 +594,7 @@ defmodule Keyword do
     end
   end
 
-  @doc """
-  Alters the value stored under `key` to `value`, but only
-  if the entry `key` already exists in the keyword list.
-
-  In the case a value is stored multiple times in the keyword list,
-  later occurrences are removed.
-
-  ## Examples
-
-      iex> Keyword.replace([a: 1, b: 2, a: 4], :a, 3)
-      [a: 3, b: 2]
-
-      iex> Keyword.replace([a: 1], :b, 2)
-      [a: 1]
-
-  """
-  @spec replace(t, key, value) :: t
+  @doc false
   def replace(keywords, key, value) when is_list(keywords) and is_atom(key) do
     case :lists.keyfind(key, 1, keywords) do
       {^key, _} -> [{key, value} | delete(keywords, key)]

lib/elixir/lib/map.ex

@@ -280,20 +280,7 @@ defmodule Map do
     end
   end
 
-  @doc """
-  Alters the value stored under `key` to `value`, but only
-  if the entry `key` already exists in `map`.
-
-  ## Examples
-
-      iex> Map.replace(%{a: 1, b: 2}, :a, 3)
-      %{a: 3, b: 2}
-
-      iex> Map.replace(%{a: 1}, :b, 2)
-      %{a: 1}
-
-  """
-  @spec replace(map, key, value) :: map
+  @doc false
   def replace(map, key, value) do
     case map do
       %{^key => _value} ->

lib/elixir/pages/Deprecations.md

@@ -15,6 +15,8 @@ Elixir deprecations happen in 3 steps:
 
 Deprecated feature                               | Deprecated in | Replaced by (available since)
 :----------------------------------------------- | :------------ | :----------------------------
+`Keyword.replace/3`                              | [v1.6]        | Use `Keyword.fetch/2` + `Keyword.put/3` (v1.0)
+`Map.replace/3`                                  | [v1.6]        | Use `Map.fetch/2` + `Map.put/3` (v1.0)
 `Macro.unescape_tokens/1` and `Macro.unescape_tokens/2` | [v1.6] | Use `Enum.map/2` to traverse over the arguments (v1.0)
 `Enum.partition/2`                               | [v1.6]        | `Enum.split_with/2` (v1.4)
 `Atom.to_char_list/1`                            | [v1.5]        | `Atom.to_charlist/1` (v1.3)

lib/elixir/src/elixir_dispatch.erl

@@ -383,10 +383,14 @@ deprecation('Elixir.Integer', to_char_list, 2) ->
   "use Integer.to_charlist/2";
 deprecation('Elixir.Kernel', to_char_list, 1) ->
   "use Kernel.to_charlist/1";
+deprecation('Elixir.Keyword', replace, 3) ->
+  "use Keyword.fetch/2 + Keyword.put/3";
 deprecation('Elixir.Keyword', size, 1) ->
   "use Kernel.length/1";
 deprecation('Elixir.List.Chars', to_char_list, 1) ->
   "use List.Chars.to_charlist/1";
+deprecation('Elixir.Map', replace, 3) ->
+  "use Map.fetch/2 + Map.put/3";
 deprecation('Elixir.Map', size, 1) ->
   "use Kernel.map_size/1";
 deprecation('Elixir.Macro', unescape_tokens, 1) ->