diff --git a/CHANGES.md b/CHANGES.md
index a27a31a80..c01c142b8 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -9,6 +9,7 @@
### Features
+* Added a new file [DEPRECATED.md](./DEPRECATED.md) to document timelines and progress of deprecated features in the Augur CLI and Python API. [#1371][] (@victorlin)
* ancestral, translate: A range of improvements to how we parse GFF and GenBank reference files. [#1351][] (@jameshadfield)
* translate will now always export a 'nuc' annotation in the output JSON, allowing it to pass validation
* Gene/CDS names of 'nuc' are now forbidden.
@@ -35,6 +36,7 @@
[#1351]: https://github.com/nextstrain/augur/pull/1351
[#1349]: https://github.com/nextstrain/augur/issues/1349
[#1367]: https://github.com/nextstrain/augur/pull/1367
+[#1371]: https://github.com/nextstrain/augur/pull/1371
## 23.1.1 (7 November 2023)
diff --git a/DEPRECATED.md b/DEPRECATED.md
new file mode 100644
index 000000000..a4ac528b7
--- /dev/null
+++ b/DEPRECATED.md
@@ -0,0 +1,21 @@
+# Deprecated
+
+These features are deprecated, which means they are no longer maintained and
+will go away in a future major version of Augur. They are currently still
+available for backwards compatibility, but should not be used in new code.
+
+## `augur export v1`
+
+*Deprecated in version 22.2.0 (July 2023). Planned for [removal](https://github.com/nextstrain/augur/issues/1266)
+January 2024 or after.*
+
+`augur export v2` was introduced in Augur version 6.0.0. Migrate by following
+the [official guide](https://docs.nextstrain.org/projects/augur/page/releases/migrating-v5-v6.html).
+
+## `augur ancestral --output`
+
+*Deprecated in version 5.2.0 (December 2019). Removed in version 7.0.0 (April
+2020).*
+
+`--output` was been replaced by `--output-node-data` to accommodate the addition
+of `--output-sequences`.
diff --git a/docs/contribute/DEV_DOCS.md b/docs/contribute/DEV_DOCS.md
index befe86e86..9af47fcf4 100644
--- a/docs/contribute/DEV_DOCS.md
+++ b/docs/contribute/DEV_DOCS.md
@@ -153,6 +153,12 @@ There are also many [editor integrations for mypy][].
[editor integrations for mypy]: https://github.com/python/mypy#integrations
+### Removing features
+
+Instead of removing a feature from one release to the next, consider first deprecating the feature
+by adding a warning output and a [deprecation entry](../../DEPRECATED.md). This allows a period of
+transition time where both the deprecated feature and a suggested alternative can be adopted.
+
### Releasing
Versions for this project, Augur, from 3.0.0 onwards aim to follow the
@@ -172,6 +178,9 @@ Versions for this project, Augur, from 3.0.0 onwards aim to follow the
```
2. Define a new version number `X.X.X` based on changes and Semantic Versioning rules.
+ > [!NOTE]
+ > If releasing a major version, consider removing a [deprecated feature](../../DEPRECATED.md).
+
##### 2. Curate [CHANGES.md](../../CHANGES.md)
1. Go through each PR and note the PRs that didn't provide an update to [CHANGES.md](../../CHANGES.md).
diff --git a/docs/releases/DEPRECATED.md b/docs/releases/DEPRECATED.md
new file mode 120000
index 000000000..ff0686962
--- /dev/null
+++ b/docs/releases/DEPRECATED.md
@@ -0,0 +1 @@
+../../DEPRECATED.md
\ No newline at end of file
diff --git a/docs/releases/breaking.md b/docs/releases/breaking.md
deleted file mode 100644
index 1dc6a0ea9..000000000
--- a/docs/releases/breaking.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Breaking Changes to `augur`
-
-This is a list of known 'breaking changes' to `augur`. These are changes that require users to modify existing scripts or calls to `augur` functions because the old usage is no longer supported. 'Deprecated' changes, which work for the moment but will no longer be supported in future, are also included.
-
-_Note this list only includes changes to `augur` code and may not cover breaking changes introduced due to changes in dependancy packages. We try to support these too, so please [open an issue](https://github.com/nextstrain/augur/issues/new) if you think you've found something we didn't catch._
-
-This list will **only** be helpful if you are _sure_ the command used to work and only stopped working after you upgraded your `augur` installation. If your `augur` installation is from earlier than 2019, or if this list doesn't solve your problem, run `--help` for the command you're using and use that information to try re-writing your call.
-
-Click on the `augur` function that used to work, and we'll try to get you up and running ASAP!
-
-* [ancestral](#ancestral)
-* [export](#export)
-
-## ancestral
-
-### `--output` argument
-
-* **Possible error/warning messages:**
- > > "WARNING: the `--output` flag will be deprecated in the next major augur release. Use `--output-node-data` instead."
-
- > > augur: error: unrecognized arguments: `--output`
-
-* **Solution:**
- To specify the JSON file to write ancestral mutations/sequences to, use the argument `--output-node-data` instead of `--output`.
-
-* **Explanation:**
- `ancestral` now supports outputting a FASTA file of reconstructed ancestral sequences (for FASTA-input runs - this was already supported in VCF-format for VCF-input runs). Users can ask for this output and specify a file name using `--output-sequences`. Since there are now two types of output from `ancestral`, the arguments have become more descriptive.
-
-
-## export
-
-### Version error
-
-* **Possible error/warning messages:**
- > > augur export: error: the following arguments are required: Augur export now needs you to define the JSON version you want, e.g. `augur export v2`.
-
-* **Solution:**
- We've upgraded `augur export`. Find out how to adjust your `augur export` call to work with the latest version [using our handy guide](migrating-v5-v6.md).
diff --git a/docs/releases/releases.rst b/docs/releases/releases.rst
index 086b16ddd..635ffdae6 100644
--- a/docs/releases/releases.rst
+++ b/docs/releases/releases.rst
@@ -15,7 +15,7 @@ and learning what you need to change should be as pain-free as possible.
:glob:
Changelog
+ Deprecated features
v6
migrating-v5-v6
- breaking
auspice-compatibility