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