<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, May 7, 2018 at 8:54 AM, José Valim <span dir="ltr"><<a href="mailto:jose.valim@gmail.com" target="_blank">jose.valim@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div><br></div></div><div><div><div>What about documentation from the OTP team that outlines a deprecation policy? It may be a good opportunity to also outline other compatibility guarantees, such as the compiled bytecode guarantees and the node compatibility guarantees, if such are not yet documented.</div></div></div></blockquote><div><br></div><div>I think it is a good idea to describe the OTP policy regarding deprecation, backward compatibility, supported releases etc. in one place. Will try to have it available before the OTP 21 release.<br><br></div><div>The Elixir policy with hard and soft deperecation is also interesting as we need to make it<br></div><div>clearer what a depercation means.<br><br><br></div><div>But in short we use the deprecation mechanism to flag that a function och application is no longer recommended for use in new code since there exist another solution that we recomment to be used instead.<br><br></div><div>We don't remove deprecated functions or applications just like that and some functions have to stay for a very long time (or forever) since there is so much usage of them.<br><br></div><div>gen_fsm is an old module which is used a lot and it is not likely to dissapear in a near future. I realize that the deprecated attribute inside the module like this<br>-<span class="gmail-pl-k">deprecated</span>({<span class="gmail-pl-c1">start</span>, <span class="gmail-pl-c1">3</span>, <span class="gmail-pl-c1">next_major_release</span>}). <br>is somewhat misleading and we will try to improve this.<br><br></div><div>/Kenneth, Erlang/OTP<br></div><div> <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div><div><div><br></div><div>We did define such document not long ago for Elixir. In terms of deprecations, we have two terms: "soft-deprecation" and "hard-deprecation". The soft-deprecation is added as soon as a new implementation exists. At this point we don't emit any warnings, but we do update the docs to say the feature will warn in the future and start to point folks towards better ways.</div><div><br></div><div>A hard-deprecation is when we finally start emitting warnings. A hard-deprecation can only be added after an alternative exists for at least 2 Elixir releases. This is very important because it means that, once a feature is hard deprecated, you know you can use the proposed alternative and that alternative is supported at least two versions back.</div><div><br></div><div>This is only necessary if a feature is being replaced. In case a feature is being removed, such as non-smp VM versions, you may skip directly to the "hard-deprecation" and emit warnings straight-away since there won’t be an alternative in the future anyway.</div><div><br></div><div>I am not proposing for Erlang/OTP team to follow those rules and conventions but writing *some* rules as minimum guarantees may improve communication and help the community plan in terms of warnings, deprecations and removals accordingly. I would just avoid emitting deprecation warnings in the same version that an alternative is introduced, because it means library developers need to either only support the latest version or introduce conditionals (either at compile-time or runtime) to support multiple versions.</div></div></div><span class="gmail-HOEnZb"><font color="#888888"><div><div><div><br></div><div class="gmail_extra"><div><div class="gmail-m_-420246517609632252m_-4686002365851403324gmail_signature"><div><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b>José Valim</b></span></div><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><div><span style="font-family:verdana,sans-serif;font-size:x-small"><a href="http://www.plataformatec.com.br/" style="color:rgb(42,93,176)" target="_blank">www.plataformatec.com.br</a></span></div><div><span style="font-family:verdana,sans-serif;font-size:x-small">Founder and </span><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div style="display:inline"><span style="font-family:verdana,sans-serif;font-size:x-small">Director of R&D</span></div></span></b></div></span></div></span></b></span></div></div></div></div>
<br></div></div></div></font></span></div><span class="gmail-HOEnZb"><font color="#888888">-- <br><div dir="ltr" class="gmail-m_-420246517609632252gmail_signature"><div dir="ltr"><div><div><br></div><div><br></div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><b>José Valim</b></span></div><div><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse"><div><span style="font-family:verdana,sans-serif;font-size:x-small"><a href="http://www.plataformatec.com.br/" style="color:rgb(42,93,176)" target="_blank">www.plataformatec.com.br</a></span></div><div><span style="font-family:verdana,sans-serif;font-size:x-small">Founder and </span><b><span style="border-collapse:separate;font-family:arial;font-weight:normal"><div style="display:inline"><span style="font-family:verdana,sans-serif;font-size:x-small">Director of R&D</span></div></span></b></div></span></div></span></b></span></div></div></div>
</font></span><br>______________________________<wbr>_________________<br>
erlang-questions mailing list<br>
<a href="mailto:erlang-questions@erlang.org">erlang-questions@erlang.org</a><br>
<a href="http://erlang.org/mailman/listinfo/erlang-questions" rel="noreferrer" target="_blank">http://erlang.org/mailman/<wbr>listinfo/erlang-questions</a><br>
<br></blockquote></div><br></div></div>