Merge pull request #1371: Add a file to keep track of deprecated feat…

…ures
nextstrain · Dec 20, 2023 · 543c433 · 543c433
2 parents 52a0366 + 171986e
commit 543c433
Show file tree

Hide file tree

Showing 6 changed files with 34 additions and 39 deletions.
diff --git 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
@@ -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
@@ -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
@@ -0,0 +1 @@
+../../DEPRECATED.md
diff --git a/docs/releases/breaking.md b/docs/releases/breaking.md
diff --git 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 <changelog>
+   Deprecated features <DEPRECATED>
    v6
    migrating-v5-v6
-   breaking
    auspice-compatibility