Deprecation attribute

_posts/2023-09-25-v0.31-keeping-dependencies-explicit.md

@@ -36,13 +36,13 @@ Here the application has specified `library_a` as a dependency in its
 `gleam.toml`, and `library_a` has specified `library_b` as a dependency in its
 own `gleam.toml`.
 
-As there's no ambiguity as to what version to use Gleam has allowed importing
-modules from packages that you don't directly depend upon, the application
-could happily import modules from `library_b`.
+As there's no ambiguity as to what version to use Gleam has historically allowed
+importing modules from packages that you don't directly depend upon. The
+application could happily import modules from `library_b`.
 
-Over time it has become clear that this form of indirect dependency is unclear
-and is confusing to a lot of folks, so we're moving to making dependencies
-explicit and only permitting imports from direct dependencies.
+Over time it we have learnt that this form of indirect dependency is unclear
+and confusing to a lot of folks, so we're moving to making dependencies explicit
+and only permitting imports from direct dependencies.
 
 With this release Gleam will now emit a warning when importing modules from a
 package your application does not directly depend upon, and in future versions
@@ -64,6 +64,37 @@ Run this command to add it to your dependencies:
     gleam add mist
 ```
 
+## Marking functions as deprecated
+
+The `@deprecated("...")` attribute has been added to allow marking functions as
+deprecated.
+
+If a deprecated function is used Gleam will emit a warning during compliation,
+informing the programmer that they need to update their code.
+
+```gleam
+pub fn main() {
+  deprecated_function()
+}
+
+@deprecated("This function is not good! Use `new_function` instead, it is better.")
+fn deprecated_function() {
+  // Inset implemenation here...
+}
+```
+
+```text
+warning: Deprecated value used
+  ┌─ /Users/louis/Desktop/thingy/src/thingy.gleam:2:3
+  │
+2 │   deprecated_function()
+  │   ^^^^^^^^^^^^^^^^^^^ This value has been deprecated
+
+It was deprecated with this message: This function is not good! Use
+`new_function` instead, it is better.
+```
+
+
 ## Quality of life improvements
 
 As we're now ramping up to version 1.0 we're making lots of small improvements