Add Deprecations page #5808

eksperimental · 2017-02-22T22:54:49Z

First draft.
I need your input where you see the "???"

let me know what you all think

eksperimental · 2017-02-22T22:56:58Z

You can see the live page formatted page here.
https://github.com/eksperimental/elixir/blob/deprecations/lib/elixir/pages/Deprecations.md

josevalim · 2017-02-23T08:54:13Z

lib/elixir/pages/Deprecations.md

@@ -0,0 +1,57 @@
+# Deprecations
+
+## Deprecation policy


Shall we call it ## Policy

josevalim · 2017-02-23T08:54:48Z

lib/elixir/pages/Deprecations.md

+  3. The feature is removed. This can only happen on major releases. This means deprecated features in Elixir v1.x shall only be removed by Elixir v2.x.
+
+
+## Table of deprecated features: modules, functions, behaviours, protocols, typespecs, attributes and arguments


What about: ## Table of deprecated features or ## Table of deprecations?

josevalim · 2017-02-23T08:55:25Z

lib/elixir/pages/Deprecations.md

+
+Deprecated feature        | Deprecated in | Replaced by             | Replacement available since
+:------------------------ | :------------ | :---------------------- | :---------------------------
+`GenEvent` module         | [v1.5]    | `Supervisor` and `GenServer`; `GenStage`; `:gen_event` | v1.0 (`Supervisor and GenServer`); v1.3 (GenStage); OTP v17.0 (`:gen_server`)


I believe you meant "OTP v17.0 (:gen_event)"

josevalim · 2017-02-23T08:55:43Z

lib/elixir/pages/Deprecations.md

+:------------------------ | :------------ | :---------------------- | :---------------------------
+`GenEvent` module         | [v1.5]    | `Supervisor` and `GenServer`; `GenStage`; `:gen_event` | v1.0 (`Supervisor and GenServer`); v1.3 (GenStage); OTP v17.0 (`:gen_server`)
+`()` to mean `nil`        | [v1.5]    | `nil`                       | v1.0
+`@compile {:parse_transform, _}` in `Module` | [v1.5] | __???__     | __???__


josevalim · 2017-02-23T08:57:53Z

lib/elixir/pages/Deprecations.md

+`Task.find/2`             | [v1.3]        | Direct message matching | v1.0
+Non-map as second arg. in `URI.decode_query/2` | [v1.3] | Use a map | v1.0
+`Access` protocol         | [v1.1]        | `Access` behaviour      | v1.1
+`?\xHEX`                  | [v1.1]        | `0xHEX`                 | __???__ (EDITOR'S NOTE: this has been completely deprecated and it shouldn't have been until v2.0)


I believe we had announced it before 1.0 but we forgot to remove it on 1.0 (doing so only on 1.1).

ok. thank you

so the 0xHEX is available since v1.0, correct?

josevalim · 2017-02-23T08:59:31Z

lib/elixir/pages/Deprecations.md

+`Access.key/1`            | [v1.4]    | `Access.key/2`              | v1.3
+`Behaviour` module        | [v1.4]    | `@callback`                 | v1.0
+`Enum.uniq/2`             | [v1.4]    | `Enum.uniq_by/2`            | v1.2
+`Float.to_char_list/2`    | [v1.4]    | `:erlang.float_to_list/2`   | OTP v17.0


We should refer to OTP as "OTP 17". WIth no v and no minor version because we don't want developers to depend on specific features based on minor OTP versions.

josevalim · 2017-02-23T08:59:59Z

lib/elixir/pages/Deprecations.md

+`IEx.Helpers.import_file/2` | [v1.4]  | `IEx.Helpers.import_file_if_available/2` | v1.3
+`Mix.Utils.underscore/1`  | [v1.4]    | `Macro.underscore/1`        | v1.2
+`Mix.Utils.camelize/1`    | [v1.4]    | `Macro.camelize/1`          | v1.2
+`Dict` behaviour          | [v1.3]    | __???__ `Keyword`; `Map`    | __???__ v1.0 (Keyword); v1.2 (Map)


This is correct (??? can be removed)

CHANGELOG for v1.2 states that states that Dict was soft-deprecated, but a warning is emitted,
936b243#diff-98fc93be50711b2d5c492ef04d076f52R48

should we update CHANGELOG?

@eksperimental we warned only for those using Dict to implement their own dicts. The API itself was OK until later. So there are two deprecations: the Dict behaviour and the Dict API. The Dict behaviour has no replacement, as there is no longer a Dict thingy to implement, the Dict API is the one you mentioned above. So I would recommend changing "Dict behaviour" by "Dict module" on this line.

exactly. so what I did was to add bellow

`Dict` behaviour | [v1.2] | *None* | *None*

still feels weird not to suggest an alternative

whatyouhide · 2017-02-23T09:05:15Z

lib/elixir/pages/Deprecations.md

+`Float.to_char_list/1`    | [v1.5]    | `Float.to_charlist/1`       | v1.3
+`Integer.to_char_list/1`  | [v1.5]    | `Integer.to_charlist/1`     | v1.3
+`Kernel.to_char_list/1`   | [v1.5]    | `Kernel.to_charlist/1`      | v1.3
+`String.to_char_list/1`   | [v1.5]    | `String.to_charlist/1`      | v1.3


There's the :charlists option in Inspect.Opts as well I believe.

whatyouhide · 2017-02-23T09:06:26Z

lib/elixir/pages/Deprecations.md

+`Keyword.size/1`          | [v1.3]        | `Kernel.length/1`       | v1.0
+`Map.size/1`              | [v1.3]        | `Kernel.map_size/1`     | v1.0
+`/r` option in `Regex`    | [v1.3]        | `/U`                    | v1.1
+`Set` behaviour           | [v1.3]        | __???__                 | __???__


There's no replacement for the behaviour, now you should just use MapSet.

josevalim · 2017-02-23T09:07:57Z

lib/elixir/pages/Deprecations.md

+`Mix.Utils.camelize/1`    | [v1.4]    | `Macro.camelize/1`          | v1.2
+`Dict` behaviour          | [v1.3]    | __???__ `Keyword`; `Map`    | __???__ v1.0 (Keyword); v1.2 (Map)
+`\x{X*}` inside strings/sigils/charlists | [v1.3] | `\uXXXX`; `\u{X*}` | v1.1
+Map/dictionary as second arg. in `Enum.group_by/3` | [v1.3] | *n/a* | *n/a*


in Enum.group_by/2. I believe we didn't have group_by/3 by then.

What about using None instead of n/a which may not be clear in intent?

@josevalim We have had Enum.group_by/3 since v1.0

josevalim · 2017-02-23T09:13:40Z

lib/elixir/pages/Deprecations.md

+Non-map as second arg. in `URI.decode_query/2` | [v1.3] | Use a map | v1.0
+`Access` protocol         | [v1.1]        | `Access` behaviour      | v1.1
+`?\xHEX`                  | [v1.1]        | `0xHEX`                 | __???__ (EDITOR'S NOTE: this has been completely deprecated and it shouldn't have been until v2.0)
+`as: true \| false` in `alias/2` and `require/2` | [v1.1]           | __???__ *n/a* | *n/a*


josevalim · 2017-02-23T09:17:45Z

This looks great, I have added some feedback. :)

eksperimental

All suggestions have been implemented.
PR is ready for a new review,
I have added comments in the rows introduced, for easier reviewing. thank you.

eksperimental · 2017-02-26T23:28:45Z

lib/elixir/pages/Deprecations.md

 `String.valid_character?/1` | [v1.3]      | `String.valid?/1`       | v1.0
 `Task.find/2`             | [v1.3]        | Direct message matching | v1.0
 Non-map as second arg. in `URI.decode_query/2` | [v1.3] | Use a map | v1.0
+`Dict` behaviour          | [v1.2]        | *None*                  | *None*


This has been added, please review.

eksperimental · 2017-02-26T23:29:21Z

lib/elixir/pages/Deprecations.md

 `Mix.Utils.underscore/1`  | [v1.4]    | `Macro.underscore/1`        | v1.2
 `Mix.Utils.camelize/1`    | [v1.4]    | `Macro.camelize/1`          | v1.2
-`Dict` behaviour          | [v1.3]    | __???__ `Keyword`; `Map`    | __???__ v1.0 (Keyword); v1.2 (Map)
+`Dict` module             | [v1.3]    | `Keyword`; `Map`            | v1.0 (`Keyword`); v1.2 (`Map`)


This has been changed from "behaviour" to "module". please review.

eksperimental · 2017-02-26T23:29:44Z

lib/elixir/pages/Deprecations.md

-`Float.to_string/2`       | [v1.4]    | `:erlang.float_to_binary/2` | OTP v17.0
+`Float.to_char_list/2`    | [v1.4]    | `:erlang.float_to_list/2`   | OTP 17
+`Float.to_string/2`       | [v1.4]    | `:erlang.float_to_binary/2` | OTP 17
+`HashDict` module         | [v1.4]    | `Map`                       | v1.2


This was not documented. And it has been added, please review.

eksperimental · 2017-02-26T23:29:54Z

lib/elixir/pages/Deprecations.md

+`Float.to_char_list/2`    | [v1.4]    | `:erlang.float_to_list/2`   | OTP 17
+`Float.to_string/2`       | [v1.4]    | `:erlang.float_to_binary/2` | OTP 17
+`HashDict` module         | [v1.4]    | `Map`                       | v1.2
+`HashSet` module          | [v1.4]    | `MapSet`                    | v1.1


This was not documented. And it has been added, please review.

eksperimental · 2017-02-26T23:30:16Z

lib/elixir/pages/Deprecations.md

 `Kernel.to_char_list/1`   | [v1.5]    | `Kernel.to_charlist/1`      | v1.3
 `String.to_char_list/1`   | [v1.5]    | `String.to_charlist/1`      | v1.3
-`t:char_list/0` typespec  | [v1.5]    | `t:charlist/0` typespec     | v1.3
+`:char_lists` key in `t:Inspect.Opts.t/0` type | [v1.5] | `:charlists` | v1.3


This was not documented. And it has been added, please review.

eksperimental · 2017-02-26T23:30:30Z

lib/elixir/pages/Deprecations.md

 `String.to_char_list/1`   | [v1.5]    | `String.to_charlist/1`      | v1.3
-`t:char_list/0` typespec  | [v1.5]    | `t:charlist/0` typespec     | v1.3
+`:char_lists` key in `t:Inspect.Opts.t/0` type | [v1.5] | `:charlists` | v1.3
+`:as_char_lists` value in `t:Inspect.Opts.t/0` type | [v1.5] | `:as_charlists` | v1.3


This was not documented. And it has been added, please review.

eksperimental

Should we add links to external docs and pages?

eksperimental · 2017-02-27T09:10:54Z

lib/elixir/pages/Deprecations.md

+:------------------------ | :------------ | :---------------------- | :---------------------------
+`Atom.to_char_list/1`     | [v1.5]    | `Atom.to_charlist/1`        | v1.3
+`Float.to_char_list/1`    | [v1.5]    | `Float.to_charlist/1`       | v1.3
+`GenEvent` module         | [v1.5]    | `Supervisor` and `GenServer`; `GenStage`; `:gen_event` | v1.0 (`Supervisor` and `GenServer`); v1.3 (`GenStage`); OTP 17 (`:gen_event`)


Should we link to GenStage and Erlang docs for :gen_event ?

I would say yes to these two because they are external to Elixir and it could help discoverability to link them.

so for GenStage, should we link to Github repo or hex package, or hexdocs page?

I think the right place is hexdocs.pm

Edit: maybe the right place is Hex though. Because it links to GitHub, to the docs, and can be considered as a general hub. Wdyt?

Yes. It looks like the Hex package page is the place to link to.

eksperimental · 2017-02-27T09:23:38Z

lib/elixir/pages/Deprecations.md

+`HashSet` module          | [v1.4]    | `MapSet`                    | v1.1
+`Set` module              | [v1.4]    | `MapSet`                    | v1.1
+`Stream.uniq/2`           | [v1.4]    | `Stream.uniq_by/2`          | v1.2
+`IEx.Helpers.import_file/2` | [v1.4]  | `IEx.Helpers.import_file_if_available/1` | v1.3


Should we link to the docs page in hexdocs.pm?

I don't think we should link all of these, they're quite a lot. :| Did you mean linking all of them?

nope. I mean those for other Elixir apps, such as IEx, which do not get linked automatically.

whatyouhide · 2017-02-27T11:25:34Z

lib/elixir/pages/Deprecations.md

+`Kernel.to_char_list/1`   | [v1.5]        | `Kernel.to_charlist/1`  | v1.3
+`String.to_char_list/1`   | [v1.5]        | `String.to_charlist/1`  | v1.3
+`()` to mean `nil`        | [v1.5]        | `nil`                   | v1.0
+`:as_char_lists` value in `t:Inspect.Opts.t/0` type | [v1.5] | `:as_charlists` | v1.3


:as_char_lists value -> :as_char_lists field

here, :as_char_lists is a value, not a key/field

Ops, missed that. Sorry!

whatyouhide · 2017-02-27T11:26:08Z

lib/elixir/pages/Deprecations.md

+`String.to_char_list/1`   | [v1.5]        | `String.to_charlist/1`  | v1.3
+`()` to mean `nil`        | [v1.5]        | `nil`                   | v1.0
+`:as_char_lists` value in `t:Inspect.Opts.t/0` type | [v1.5] | `:as_charlists` | v1.3
+`:char_lists` key in `t:Inspect.Opts.t/0` type | [v1.5] | `:charlists` | v1.3


key ->field

whatyouhide · 2017-02-27T11:26:24Z

lib/elixir/pages/Deprecations.md

+`()` to mean `nil`        | [v1.5]        | `nil`                   | v1.0
+`:as_char_lists` value in `t:Inspect.Opts.t/0` type | [v1.5] | `:as_charlists` | v1.3
+`:char_lists` key in `t:Inspect.Opts.t/0` type | [v1.5] | `:charlists` | v1.3
+`char_list/0` type        | [v1.5]        | `charlist/0` type       | v1.3


Should this be linked with t:?

since it's built in, it doesn't link to anything and it leaves the t:.
I think it's an ExDoc bug. While it doesn't link, it should still remove the t:

eksperimental · 2017-02-27T12:44:28Z

@josevalim @whatyouhide could you please review the lines commented in #5808 (review)
the code is outdated, but the lines are still valid. it is just rows that has been introduced after the first commit

josevalim · 2017-02-27T13:39:40Z

lib/elixir/pages/Deprecations.md

+`Dict` module             | [v1.3]        | `Keyword`; `Map`        | v1.0 (`Keyword`); v1.2 (`Map`)
+`Keyword.size/1`          | [v1.3]        | `Kernel.length/1`       | v1.0
+`Map.size/1`              | [v1.3]        | `Kernel.map_size/1`     | v1.0
+`Set` behaviour           | [v1.3]        | *None*                  | *None*


Theoretically the replacement for Set behaviour is to use MapSet directly.

josevalim · 2017-02-27T13:39:58Z

lib/elixir/pages/Deprecations.md

+`Set` behaviour           | [v1.3]        | *None*                  | *None*
+`String.valid_character?/1` | [v1.3]      | `String.valid?/1`       | v1.0
+`Task.find/2`             | [v1.3]        | Direct message matching | v1.0
+`:append_first` option in `Kernel.defdelegate/2` | [v1.3] | *None*  | *None*


Theoretically the replacement is defining the function directly.

josevalim · 2017-02-27T13:41:07Z

lib/elixir/pages/Deprecations.md

+`Access` protocol         | [v1.1]        | `Access` behaviour      | v1.1
+`as: true \| false` in `alias/2` and `require/2` | [v1.1] | *None*  | *None*
+`?\xHEX`                  | [v1.1]        | `0xHEX`                 | v1.0
+Empty string in `String.starts_with?/2`, `String.ends_with?/2`, `String.contains?/2`. *__NOTE__: Feature made back available in v1.3* | [v1.1] to [v1.2] | *None* | *None*


Theoretically the replacement is to explicitly check for "" for before hand.

josevalim · 2017-02-27T13:41:51Z

@eksperimental do we plan to include syntax deprecations? Such as local_fun_as_variable and fn -> end?

eksperimental · 2017-02-27T13:48:05Z

yes, I think we should. Anything that emits a warning should be listed here,

what is the fn -> end deprecation?

josevalim · 2017-02-27T13:53:33Z

iex(1)> fn -> end
warning: an expression is always required on the right side of ->. Please provide a value after ->
  iex:1

eksperimental · 2017-03-03T16:41:02Z

I have addressed all the suggestions,
Please have a look at the "None"s and let me know if there is an alternative.

Also I am thinking that there are more syntax deprecations to add. What we could do is to split the table in two. One for Syntax and one for the rest.
But it would leave this as it is for now, merge it and then work on those in a second PR

WDYGT?

josevalim · 2017-03-03T20:30:46Z

If we are worried about the table size we can also break the table per application. Although that may not help much.

josevalim · 2017-03-03T20:31:36Z

lib/elixir/pages/Deprecations.md

+`\x{X*}` inside strings/sigils/charlists | [v1.3] | `\uXXXX`; `\u{X*}` | v1.1
+Map or dictionary as second argument in `Enum.group_by/3` | [v1.3] | Pass a function | v1.3
+Non-map as second argument in `URI.decode_query/2` | [v1.3] | Use a map | v1.0
+`Dict` behaviour          | [v1.2]        | *None*                  | *None*


The replacement is the Map data structure (similar to Set being the MapSet data structure).

josevalim · 2017-03-03T20:31:59Z

@eksperimental I gave another pass and found only one place where we could change None to something else. I have added it as a comment. ❤️

eksperimental · 2017-03-04T03:44:50Z

I have merged the last two columns.
This is ready for a final review/merging.
thank you everyone for your input

whatyouhide · 2017-03-04T09:36:36Z

Thanks! 💟

WIP: Add Deprecations page

cfb8b73

eksperimental force-pushed the deprecations branch from 8f8f340 to cfb8b73 Compare February 23, 2017 01:28

josevalim reviewed Feb 23, 2017

View reviewed changes

whatyouhide reviewed Feb 23, 2017

View reviewed changes

josevalim reviewed Feb 23, 2017

View reviewed changes

Deprecation page: corrections

c995b46

eksperimental force-pushed the deprecations branch from a0b039c to c995b46 Compare February 26, 2017 03:32

eksperimental added 2 commits February 27, 2017 06:10

WIP: Deprecations page: sort table

b978cda

Use "argument" instead of "arg."

528a1e1

eksperimental commented Feb 26, 2017

View reviewed changes

eksperimental added 3 commits February 27, 2017 16:06

remove from types

f6c714f

Correct :gen_event spelling

4dfb9ac

Correct arity in IEx.Helpers.import_file_if_available/1

90a9b85

eksperimental commented Feb 27, 2017

View reviewed changes

eksperimental added 3 commits February 27, 2017 17:26

Add external links

1c69020

Align table

df34f00

Improve wording

7c91700

whatyouhide requested changes Feb 27, 2017

View reviewed changes

josevalim reviewed Feb 27, 2017

View reviewed changes

Include suggestions by José Valim

69f9c6e

eksperimental mentioned this pull request Mar 3, 2017

Autolink should deal with built-in types differently elixir-lang/ex_doc#682

Closed

josevalim reviewed Mar 3, 2017

View reviewed changes

eksperimental added 2 commits March 4, 2017 09:56

Add Dict behaviour alternative

eef7d89

Join last two columns in deprecation table

9e0d711

eksperimental changed the title ~~WIP: Add Deprecations page~~ Add Deprecations page Mar 4, 2017

josevalim approved these changes Mar 4, 2017

View reviewed changes

whatyouhide approved these changes Mar 4, 2017

View reviewed changes

whatyouhide merged commit 4020b7e into elixir-lang:master Mar 4, 2017

eksperimental deleted the deprecations branch March 4, 2017 12:11

		3. The feature is removed. This can only happen on major releases. This means deprecated features in Elixir v1.x shall only be removed by Elixir v2.x.


		## Table of deprecated features: modules, functions, behaviours, protocols, typespecs, attributes and arguments

Add Deprecations page #5808

Add Deprecations page #5808

Uh oh!

Conversation

eksperimental commented Feb 22, 2017

Uh oh!

eksperimental commented Feb 22, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josevalim Feb 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eksperimental Feb 25, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josevalim commented Feb 23, 2017

Uh oh!

eksperimental left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eksperimental left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

whatyouhide Feb 27, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

josevalim Feb 25, 2017 •

edited

Loading

eksperimental Feb 25, 2017 •

edited

Loading

eksperimental left a comment •

edited

Loading

whatyouhide Feb 27, 2017 •

edited

Loading