From d5e2191f269aba12809496101eb18bbc6673f87e Mon Sep 17 00:00:00 2001
From: Michael Crumm <michael.crumm@cargosense.com>
Date: Wed, 15 Nov 2023 16:24:59 -0800
Subject: [PATCH] Update changelog

---
 CHANGELOG.md | 44 ++++++++++++++++++++++++++++++++++++--------
 mix.exs      |  4 ++--
 2 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dd6db93..91dd80a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,41 @@
+# Changelog
+
 ## v0.5.0
 
+This version changes the Briefly API, so read the notes below and upgrade with care.
+
+- Change the return value of `Briefly.create/1` to be either `{:ok, path}` or
+  `{:error, Exception.t()}`. The following exceptions may be returned:
+
+  - `%Briefly.NoRootDirectoryError{}` - Briefly is unable to create a root temporary
+    directory. The exception contains the temp dirs attempted.
+
+  - `%Briefly.WriteError{}` - A temporary entry cannot be created. The exception
+    contains the POSIX error code the caused the failure.
+
+For example, if you have this:
+
+```elixir
+case Briefly.create() do
+  {:ok, path} -> path
+  {:no_space, _} -> raise "no space"
+  {:too_many_attempts, _} -> raise "too many attempts"
+  {:no_tmp, _} -> raise "no tmp dirs"
+end
+```
+
+...then change it to this:
+
+```elixir
+case Briefly.create() do
+  {:ok, path} -> path
+  {:error, %Briefly.WriteError{code: :enospc}} -> raise "no space"
+  {:error, %Briefly.WriteError{code: c}} when c in [:eexist, :eacces] -> raise "too many attempts"
+  {:error, %Briefly.NoRootDirectoryError{}} -> raise "no tmp dirs"
+  {:error, exception} when is_exception(exception) -> raise exception
+end
+```
+
 - Add `Briefly.give_away/3` to transfer ownership of a tmp file.
 - Deprecate the `:monitor_pid` option.
 
@@ -16,14 +52,6 @@ If you were previously using `:monitor_pid` like this:
 :ok = Briefly.give_away(path, pid)
 ```
 
-### Exceptions
-
-The following exceptions may now be returned from `Briefly.create/1`:
-
-- `%Briefly.NoRootDirectoryError{}` - returned when a root temporary directory could not be accessed.
-
-- `%Briefly.WriteError{}` - returned when an entry cannot be created.
-
 ## v0.4.1 (2023-01-11)
 
 - Fix an issue with custom tmp dirs without a trailing slash ([#24](https://github.com/CargoSense/briefly/pull/24)) @srgpqt
diff --git a/mix.exs b/mix.exs
index 37b4ccd..7edfec9 100644
--- a/mix.exs
+++ b/mix.exs
@@ -35,7 +35,7 @@ defmodule Briefly.Mixfile do
   defp package do
     [
       description: "Simple, robust temporary file support",
-      files: ["lib", "config", "mix.exs", "README*", "LICENSE"],
+      files: ["lib", "config", "mix.exs", "README*", "LICENSE", "CHANGELOG.md"],
       contributors: ["Bruce Williams", "Michael A. Crumm Jr."],
       licenses: ["Apache-2.0"],
       links: %{"GitHub" => @source_url}
@@ -49,7 +49,7 @@ defmodule Briefly.Mixfile do
       language: "en",
       formatters: ["html"],
       main: "usage",
-      extras: ["guides/usage.livemd"]
+      extras: ["guides/usage.livemd", "CHANGELOG.md"]
     ]
   end