From c8f8335c14ce553b52d1dacd1f4a7971f46e687c Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Wed, 31 Jan 2018 08:40:05 -0500 Subject: [PATCH 01/10] Add deprecation process DIP --- DIPs/DIP1xxx-JS.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 DIPs/DIP1xxx-JS.md diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md new file mode 100644 index 000000000..a1898fcf8 --- /dev/null +++ b/DIPs/DIP1xxx-JS.md @@ -0,0 +1,75 @@ +# The Deprecation Process + +| Field | Value | +|-----------------|-----------------------------------------------------------------| +| DIP: | xxxx | +| Review Count: | 0 | +| Author: | Jack Stouffer | +| Implementation: | N/A | +| Status: | Draft | + +## Abstract + +In order to incrementally improve D or it's standard library, it's often necessary to +mark features or functions for future removal. This document proposes a standardized +process for language maintainers to remove public features. This process would be +used across DMD, Druntime, and Phobos. + +## Rationale + +There is general disagreement on the best and/or accepted way to remove public +features. Each deprecation ends being handled slightly differently depending on +who's handling the pull requests. Standardizing the process makes sure that +deprecations are done very publicly and carefully, as to minimize breakage and +to provide clear fixes for user code. + +## Description + +The following lays out the rules to follow to deprecate a part of D. + +A symbol or feature must not be marked for removal on a specific date, but rather on a +specific release. This allows users to easily know if upgrading will break their +code or not. + +Both at the time of deprecation and removal, a changelog entry must be made. + +### Public Functions, Types, and Modules + +The symbol(s) must be marked using the `deprecated` keyword with a message containing +the planned removal period and/or a pointer to more information pertaining to the +deprecation. The documentation of the symbol(s) must be updated noting the +deprecation and removal plan. The documentation should contain information to help +the users using the symbol(s) transition their code away from the symbol(s). + +Users must be given at least four major releases before the deprecated symbols +are removed. More releases should be given if the removed code is commonly used. + +On the third release, the documentation for the symbol should be removed while +keeping it public. + +If there is no equivalent for the functionality of the removed symbol in the +standard library or the runtime, the code should be moved to +[undeaD](https://github.com/dlang/undeaD) to allow users to keep their current +code if refactoring is not possible. + +### Language Features + +If the language feature is determined to be common, a command line flag should +be added in the form of `-transition=[name]` which gives the deprecation message +in advance of yielding a deprecation message by default. If this approach is used, +users must be given at least two major releases before not using the flag gives +deprecation messages. The transition flag would then have no effect, and turn +into an error when the deprecated feature is finally removed. + +Users must be given at least four major releases before the deprecated features +are removed. More releases should be given if the removed code is commonly used. + +Warnings should NOT be used in the deprecation process. Warnings are set as errors +in many build systems (including DUB), and would therefore prematurely break many +user's code. + +## Copyright & License + +Copyright (c) 2017 by the D Language Foundation + +Licensed under [Creative Commons Zero 1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt) From 601379985102bcf36c2596804e23279bddd111c1 Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Wed, 31 Jan 2018 14:32:11 -0500 Subject: [PATCH 02/10] Address reviews --- DIPs/DIP1xxx-JS.md | 35 +++++++++++++++++++++++------------ 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index a1898fcf8..4d3258325 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -31,7 +31,19 @@ A symbol or feature must not be marked for removal on a specific date, but rathe specific release. This allows users to easily know if upgrading will break their code or not. -Both at the time of deprecation and removal, a changelog entry must be made. +At the time of the pull request for deprecation, all code in Phobos, Druntime, +and DMD must be updated to remove use of the effected code. Any projects that +are tested on the Project Tester that are broken should also have their +maintainers notified. + +Both at the time of deprecation and removal, a changelog entry must be made. This +changelog entry should have a short motivation for the deprecation (or removal) +and should to describe what steps can be taken by the user to upgrade their codebase. + +In order to facilitate on schedule deprecations, a comment of the format +`@@@DEPRECATED_[version]@@@` should be added to the top of the code to be removed/disabled. +This comment allows code to be easily searched before every release to +catch all planned deprecations. ### Public Functions, Types, and Modules @@ -41,10 +53,10 @@ deprecation. The documentation of the symbol(s) must be updated noting the deprecation and removal plan. The documentation should contain information to help the users using the symbol(s) transition their code away from the symbol(s). -Users must be given at least four major releases before the deprecated symbols +Users must be given at least four non-patch releases before the deprecated symbols are removed. More releases should be given if the removed code is commonly used. -On the third release, the documentation for the symbol should be removed while +On the second release, the documentation for the symbol should be removed while keeping it public. If there is no equivalent for the functionality of the removed symbol in the @@ -54,19 +66,18 @@ code if refactoring is not possible. ### Language Features -If the language feature is determined to be common, a command line flag should -be added in the form of `-transition=[name]` which gives the deprecation message -in advance of yielding a deprecation message by default. If this approach is used, -users must be given at least two major releases before not using the flag gives -deprecation messages. The transition flag would then have no effect, and turn -into an error when the deprecated feature is finally removed. +Deprecations to language features must also update the [language deprecations +page](https://dlang.org/deprecate.html) on dlang.org simultaneously. -Users must be given at least four major releases before the deprecated features +Users must be given at least four non-patch releases before the deprecated features are removed. More releases should be given if the removed code is commonly used. -Warnings should NOT be used in the deprecation process. Warnings are set as errors +Warnings must NOT be used in the deprecation process. Warnings are set as errors in many build systems (including DUB), and would therefore prematurely break many -user's code. +user's code. The exception is when the deprecation is for a change which turns +something into a warning. In this case the code which would trigger the warning must +also first go through a deprecation period. + ## Copyright & License From 7b125949904a71c066cdfb76f4df98e664e9261a Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Thu, 1 Feb 2018 10:28:39 -0500 Subject: [PATCH 03/10] Address reviews and comment more on language changes --- DIPs/DIP1xxx-JS.md | 43 +++++++++++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index 4d3258325..b31845fbe 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -31,6 +31,18 @@ A symbol or feature must not be marked for removal on a specific date, but rathe specific release. This allows users to easily know if upgrading will break their code or not. +Users must be given at least eight non-patch releases before the deprecated features +are removed. More releases can be given if the removed code is commonly used. +There are two cases where the deprecation period is allowed to be shorter: + +1. The code or feature is notably dangerous or unsafe, and users need to remove +it from their code as soon as possible. +2. The existance of the current code precludes its own fix or the fix of an equally +important issue. + +Shorting the deprecation preiod should be done with caution to avoid giving D +an image of instability. + At the time of the pull request for deprecation, all code in Phobos, Druntime, and DMD must be updated to remove use of the effected code. Any projects that are tested on the Project Tester that are broken should also have their @@ -47,17 +59,22 @@ catch all planned deprecations. ### Public Functions, Types, and Modules +All removals (or changes that make the code `private`/`package`) of public functions, +types, and modules must be accompanied with a deprecation period. + The symbol(s) must be marked using the `deprecated` keyword with a message containing the planned removal period and/or a pointer to more information pertaining to the deprecation. The documentation of the symbol(s) must be updated noting the deprecation and removal plan. The documentation should contain information to help the users using the symbol(s) transition their code away from the symbol(s). -Users must be given at least four non-patch releases before the deprecated symbols -are removed. More releases should be given if the removed code is commonly used. +If the deprecation is occuring because the symbol(s) are being replaced by new +symbols, both the old and the new symbol(s) should be availible un-deprecated +in at least one release to allow users to build their code without issue on +both the `stable` and `master` branches. -On the second release, the documentation for the symbol should be removed while -keeping it public. +On the fourth release in the deprecation period, the documentation for the symbol +should be removed while keeping the code itself public until removal. If there is no equivalent for the functionality of the removed symbol in the standard library or the runtime, the code should be moved to @@ -66,11 +83,18 @@ code if refactoring is not possible. ### Language Features -Deprecations to language features must also update the [language deprecations -page](https://dlang.org/deprecate.html) on dlang.org simultaneously. +Unless the removed language feature is very unsafe or causes damage to real +world systems, all changes or removals must be accompanied with a deprecation +period. "Language features" includes bugs in the current behavior that existing +user code depends on, e.g. [Issue 10378](https://issues.dlang.org/show_bug.cgi?id=10378). +Fixing such issues should include a deprecation preiod for the current behavior, +and an introduction of the new behavior as the default only at the end of the +period. -Users must be given at least four non-patch releases before the deprecated features -are removed. More releases should be given if the removed code is commonly used. +Deprecations to language features must also update the [language deprecations +page](https://dlang.org/deprecate.html) on dlang.org simultaneously. The deprecation +message given by the compiler should contain the planned removal period and/or a +pointer to more information pertaining to the deprecation. Warnings must NOT be used in the deprecation process. Warnings are set as errors in many build systems (including DUB), and would therefore prematurely break many @@ -78,9 +102,8 @@ user's code. The exception is when the deprecation is for a change which turns something into a warning. In this case the code which would trigger the warning must also first go through a deprecation period. - ## Copyright & License -Copyright (c) 2017 by the D Language Foundation +Copyright (c) 2018 by the D Language Foundation Licensed under [Creative Commons Zero 1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt) From e2277274590ae300cf5732c2febadd75af969aff Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Thu, 1 Feb 2018 11:31:40 -0500 Subject: [PATCH 04/10] Update DIP1xxx-JS.md --- DIPs/DIP1xxx-JS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index b31845fbe..3b6ffe88b 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -20,7 +20,7 @@ used across DMD, Druntime, and Phobos. There is general disagreement on the best and/or accepted way to remove public features. Each deprecation ends being handled slightly differently depending on who's handling the pull requests. Standardizing the process makes sure that -deprecations are done very publicly and carefully, as to minimize breakage and +deprecations are done very publicly and carefully, so as to minimize breakage and to provide clear fixes for user code. ## Description @@ -31,7 +31,7 @@ A symbol or feature must not be marked for removal on a specific date, but rathe specific release. This allows users to easily know if upgrading will break their code or not. -Users must be given at least eight non-patch releases before the deprecated features +Users must be given at least 10 non-patch releases before the deprecated features are removed. More releases can be given if the removed code is commonly used. There are two cases where the deprecation period is allowed to be shorter: @@ -73,7 +73,7 @@ symbols, both the old and the new symbol(s) should be availible un-deprecated in at least one release to allow users to build their code without issue on both the `stable` and `master` branches. -On the fourth release in the deprecation period, the documentation for the symbol +On the fifth release in the deprecation period, the documentation for the symbol should be removed while keeping the code itself public until removal. If there is no equivalent for the functionality of the removed symbol in the @@ -87,7 +87,7 @@ Unless the removed language feature is very unsafe or causes damage to real world systems, all changes or removals must be accompanied with a deprecation period. "Language features" includes bugs in the current behavior that existing user code depends on, e.g. [Issue 10378](https://issues.dlang.org/show_bug.cgi?id=10378). -Fixing such issues should include a deprecation preiod for the current behavior, +Fixing such issues should include a deprecation period for the current behavior, and an introduction of the new behavior as the default only at the end of the period. From ac2f5cc49c66392e0d961d5ab7ad06977e43585f Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Thu, 1 Feb 2018 11:32:21 -0500 Subject: [PATCH 05/10] Update DIP1xxx-JS.md --- DIPs/DIP1xxx-JS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index 3b6ffe88b..d1e7c3296 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -18,7 +18,7 @@ used across DMD, Druntime, and Phobos. ## Rationale There is general disagreement on the best and/or accepted way to remove public -features. Each deprecation ends being handled slightly differently depending on +features. Each deprecation ends up being handled slightly differently depending on who's handling the pull requests. Standardizing the process makes sure that deprecations are done very publicly and carefully, so as to minimize breakage and to provide clear fixes for user code. From 63d4fe8a4d36636212a4a51d1f187dd84fbfb1e3 Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Thu, 1 Feb 2018 12:05:07 -0500 Subject: [PATCH 06/10] Update DIP1xxx-JS.md --- DIPs/DIP1xxx-JS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index d1e7c3296..e59bd7627 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -63,8 +63,9 @@ All removals (or changes that make the code `private`/`package`) of public funct types, and modules must be accompanied with a deprecation period. The symbol(s) must be marked using the `deprecated` keyword with a message containing -the planned removal period and/or a pointer to more information pertaining to the -deprecation. The documentation of the symbol(s) must be updated noting the +the planned removal period. A pointer to more information should also be added. E.g. +"See the 2.080 changelog for more details" or "See the function documentation for more +details". The documentation of the symbol(s) must be updated noting the deprecation and removal plan. The documentation should contain information to help the users using the symbol(s) transition their code away from the symbol(s). From e25585bc7943169ce6415deff6eb3aaa088f11ce Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Thu, 1 Mar 2018 11:31:14 -0500 Subject: [PATCH 07/10] Update DIP1xxx-JS.md --- DIPs/DIP1xxx-JS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index e59bd7627..e46a204db 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -40,7 +40,7 @@ it from their code as soon as possible. 2. The existance of the current code precludes its own fix or the fix of an equally important issue. -Shorting the deprecation preiod should be done with caution to avoid giving D +Shorting the deprecation period should be done with caution to avoid giving D an image of instability. At the time of the pull request for deprecation, all code in Phobos, Druntime, From 8336515732fdec86675a29c760cd8b07bd01583c Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Wed, 7 Mar 2018 08:53:13 -0500 Subject: [PATCH 08/10] Update DIP1xxx-JS.md --- DIPs/DIP1xxx-JS.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index e46a204db..235720b39 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -1,12 +1,12 @@ # The Deprecation Process -| Field | Value | +| Field | Value | |-----------------|-----------------------------------------------------------------| -| DIP: | xxxx | -| Review Count: | 0 | -| Author: | Jack Stouffer | -| Implementation: | N/A | -| Status: | Draft | +| DIP: | 10XX | +| Review Count: | 0 | +| Author: | Jack Stouffer | +| Implementation: | N/A | +| Status: | | ## Abstract @@ -15,6 +15,12 @@ mark features or functions for future removal. This document proposes a standard process for language maintainers to remove public features. This process would be used across DMD, Druntime, and Phobos. +## Contents +* [Rationale](#rationale) +* [Description](#description) +* [Acknowledgements](#acknowledgements) +* [Reviews](#reviews) + ## Rationale There is general disagreement on the best and/or accepted way to remove public @@ -108,3 +114,8 @@ also first go through a deprecation period. Copyright (c) 2018 by the D Language Foundation Licensed under [Creative Commons Zero 1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt) + +## Review + +The DIP Manager will supplement this section with a summary of each review stage +of the DIP process beyond the Draft Review. From 6a0138f3f024484e7ec910278aca513f7d971251 Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Mon, 26 Mar 2018 08:49:23 -0400 Subject: [PATCH 09/10] Update DIP1xxx-JS.md --- DIPs/DIP1xxx-JS.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index 235720b39..26892bb50 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -18,14 +18,16 @@ used across DMD, Druntime, and Phobos. ## Contents * [Rationale](#rationale) * [Description](#description) -* [Acknowledgements](#acknowledgements) + * [Public Functions, Types, and Modules](#public-functions-types-and-modules) + * [Language Features](#language-features) +* [Copyright & License](#copyright--license) * [Reviews](#reviews) ## Rationale There is general disagreement on the best and/or accepted way to remove public features. Each deprecation ends up being handled slightly differently depending on -who's handling the pull requests. Standardizing the process makes sure that +who's writing the pull request. Standardizing the process makes sure that deprecations are done very publicly and carefully, so as to minimize breakage and to provide clear fixes for user code. @@ -43,10 +45,10 @@ There are two cases where the deprecation period is allowed to be shorter: 1. The code or feature is notably dangerous or unsafe, and users need to remove it from their code as soon as possible. -2. The existance of the current code precludes its own fix or the fix of an equally +2. The existence of the current code precludes its own fix or the fix of an equally important issue. -Shorting the deprecation period should be done with caution to avoid giving D +Shortening the deprecation period should be done with caution to avoid giving D an image of instability. At the time of the pull request for deprecation, all code in Phobos, Druntime, @@ -56,7 +58,7 @@ maintainers notified. Both at the time of deprecation and removal, a changelog entry must be made. This changelog entry should have a short motivation for the deprecation (or removal) -and should to describe what steps can be taken by the user to upgrade their codebase. +and should describe which steps can be taken by the user to upgrade their codebase. In order to facilitate on schedule deprecations, a comment of the format `@@@DEPRECATED_[version]@@@` should be added to the top of the code to be removed/disabled. @@ -80,8 +82,11 @@ symbols, both the old and the new symbol(s) should be availible un-deprecated in at least one release to allow users to build their code without issue on both the `stable` and `master` branches. -On the fifth release in the deprecation period, the documentation for the symbol -should be removed while keeping the code itself public until removal. +On the first release in the deprecation period, the removed symbol(s) should +be removed from any module or package wide list of public functions/booktables/cheatsheets +to demphize its use. On the fifth release in the deprecation period, the documentation +for the symbol should be removed completely while keeping the code itself public until +complete removal. If there is no equivalent for the functionality of the removed symbol in the standard library or the runtime, the code should be moved to @@ -115,7 +120,7 @@ Copyright (c) 2018 by the D Language Foundation Licensed under [Creative Commons Zero 1.0](https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt) -## Review +## Reviews The DIP Manager will supplement this section with a summary of each review stage of the DIP process beyond the Draft Review. From 77064132ce8e51057a084b156a30dfb5ec175640 Mon Sep 17 00:00:00 2001 From: Jack Stouffer Date: Wed, 28 Mar 2018 14:02:57 -0400 Subject: [PATCH 10/10] Update DIP1xxx-JS.md --- DIPs/DIP1xxx-JS.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/DIPs/DIP1xxx-JS.md b/DIPs/DIP1xxx-JS.md index 26892bb50..69b7cdc3b 100644 --- a/DIPs/DIP1xxx-JS.md +++ b/DIPs/DIP1xxx-JS.md @@ -26,18 +26,18 @@ used across DMD, Druntime, and Phobos. ## Rationale There is general disagreement on the best and/or accepted way to remove public -features. Each deprecation ends up being handled slightly differently depending on +features. Each deprecation ends up being handled with slight variations depending on who's writing the pull request. Standardizing the process makes sure that deprecations are done very publicly and carefully, so as to minimize breakage and to provide clear fixes for user code. ## Description -The following lays out the rules to follow to deprecate a part of D. +The following lays out a new procedure for deprecating a part of D. A symbol or feature must not be marked for removal on a specific date, but rather on a -specific release. This allows users to easily know if upgrading will break their -code or not. +specific release. This allows users to easily determine if upgrading will break their +code. Users must be given at least 10 non-patch releases before the deprecated features are removed. More releases can be given if the removed code is commonly used. @@ -52,9 +52,9 @@ Shortening the deprecation period should be done with caution to avoid giving D an image of instability. At the time of the pull request for deprecation, all code in Phobos, Druntime, -and DMD must be updated to remove use of the effected code. Any projects that -are tested on the Project Tester that are broken should also have their -maintainers notified. +and DMD must be updated to remove use of the effected code. Maintainers of any +projects which are tested on the Project Tester and are broken by the deprecation +should be notified. Both at the time of deprecation and removal, a changelog entry must be made. This changelog entry should have a short motivation for the deprecation (or removal) @@ -63,28 +63,28 @@ and should describe which steps can be taken by the user to upgrade their codeba In order to facilitate on schedule deprecations, a comment of the format `@@@DEPRECATED_[version]@@@` should be added to the top of the code to be removed/disabled. This comment allows code to be easily searched before every release to -catch all planned deprecations. +find all planned deprecations. -### Public Functions, Types, and Modules +### Public Functions, Variables, Types, and Modules -All removals (or changes that make the code `private`/`package`) of public functions, -types, and modules must be accompanied with a deprecation period. +All removals or changes to protection attributes of public functions, +variables, types, and modules must be accompanied with a deprecation period. The symbol(s) must be marked using the `deprecated` keyword with a message containing -the planned removal period. A pointer to more information should also be added. E.g. +the planned removal period. A reference to more information should also be added. E.g. "See the 2.080 changelog for more details" or "See the function documentation for more details". The documentation of the symbol(s) must be updated noting the deprecation and removal plan. The documentation should contain information to help -the users using the symbol(s) transition their code away from the symbol(s). +the users of the symbol(s) transition their code away from the symbol(s). If the deprecation is occuring because the symbol(s) are being replaced by new -symbols, both the old and the new symbol(s) should be availible un-deprecated -in at least one release to allow users to build their code without issue on -both the `stable` and `master` branches. +symbols, both the old and the new symbol(s) should be available without a +deprecation message in at least one release to allow users to build their code +without issue on both the `stable` and `master` branches. On the first release in the deprecation period, the removed symbol(s) should be removed from any module or package wide list of public functions/booktables/cheatsheets -to demphize its use. On the fifth release in the deprecation period, the documentation +to deemphasize its use. On the fifth release in the deprecation period, the documentation for the symbol should be removed completely while keeping the code itself public until complete removal. @@ -97,8 +97,8 @@ code if refactoring is not possible. Unless the removed language feature is very unsafe or causes damage to real world systems, all changes or removals must be accompanied with a deprecation -period. "Language features" includes bugs in the current behavior that existing -user code depends on, e.g. [Issue 10378](https://issues.dlang.org/show_bug.cgi?id=10378). +period. "Language features" includes bugs in the current behavior upon which +existing code depends, e.g. [Issue 10378](https://issues.dlang.org/show_bug.cgi?id=10378). Fixing such issues should include a deprecation period for the current behavior, and an introduction of the new behavior as the default only at the end of the period. @@ -106,13 +106,13 @@ period. Deprecations to language features must also update the [language deprecations page](https://dlang.org/deprecate.html) on dlang.org simultaneously. The deprecation message given by the compiler should contain the planned removal period and/or a -pointer to more information pertaining to the deprecation. +reference to more information pertaining to the deprecation. Warnings must NOT be used in the deprecation process. Warnings are set as errors in many build systems (including DUB), and would therefore prematurely break many -user's code. The exception is when the deprecation is for a change which turns -something into a warning. In this case the code which would trigger the warning must -also first go through a deprecation period. +user's code. The exception is when a change deprecates a feature which is intended +to turn something into a warning. In this case the code which would trigger the +warning must also first go through a deprecation period. ## Copyright & License