From 569656abf81531de7b0d4ccfa8463bcc1d4b5fc5 Mon Sep 17 00:00:00 2001 From: Brett Date: Tue, 19 Sep 2023 15:21:59 -0400 Subject: [PATCH] update docs for 3.0 release --- docs/asdf/whats_new.rst | 94 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/docs/asdf/whats_new.rst b/docs/asdf/whats_new.rst index b6824d7ac..e5148af79 100644 --- a/docs/asdf/whats_new.rst +++ b/docs/asdf/whats_new.rst @@ -6,6 +6,100 @@ What's New ********** +.. _whats_new_3.0.0: + +3.0.0 +===== + +Asdf 3.0.0 is the first major asdf release since 2018. + +Thank you to all the +`contributors `_! + +.. _whats_new_3.0.0_removed: + +Removed features +---------------- + +The following deprecated features are removed in asdf 3.0.0: + +* :ref:`AsdfInFits ` +* :ref:`Legacy Extensions ` + +Please see the links above or the :ref:`deprecations` for more details. + +.. _whats_new_3.0.0__ew_features: + +New features +------------ + +As asdf now only supports new-style :ref:`extensions ` several +new features were added to allow these extensions to retain all the +functionality of the now removed type system. + +Converters can now :ref:`defer ` conversion allowing +a different converter to handle serailizing an object. This is useful if a +subclass instance can be safely converted to a superclass during serialization. +See :ref:`extending_converters_deferral` for an example and more information. + +Converters can now access :ref:`ASDF block storage `. +during serialization and deserializtion. See :ref:`extending_converter_block_storage` +for examples and more information. + +Converters have always been "strict" about tag version mismatches +(returning 'raw' objects if a specific tag version is not supported). This +"strictness" now extends to all objects handled by asdf. As all known asdf +extensions have already migrated to converters this should pose no issue +for users. Please `open an issue `_ +if you run into any difficulty. + +.. whats_new_3.0.0_internal: + +Internal changes +---------------- + +2.15.1 included internally a version of jsonschema. See the +:ref:`jsonschema ` sub-section of the +:ref:`2.15.1 ` section for more details. Asdf 3.0.0 drops +jsonschema as a dependency. If your software requires jsonschema be sure to add +it to your dependencies. + +To accomplish the above improvements to asdf extensions, a major rewrite of +the ASDF block management code was required. During this rewrite +``AsdfBlockIndexWarning`` was added which users will see if they open an ASDF +file with an invalid block index. Re-saving the file (or removing the +optional block index) is often sufficient to fix the file so it no longer +issues the warning when opened. + +.. whats_new_3.0.0_upcoming: + +Upcoming changes +---------------- + +With the release of asdf 3.0.0 the developers are beginning work on 3.1.0 and +4.0.0. One major change being considered for asdf 4.0.0 is the disabling of +memory mapping as the default option when as ASDF file is opened. Memory +mapping can offer significant performance gains but also increases the chance +for gnarly errors like segfaults and corrupt data. Please let us know if +this change would impact your use of asdf in the newly opened +`asdf discussions `_ + +In an attempt to construct a coherent api, asdf 3.1 (and additional minor +versions) will likely contain new deprecations in an effort to reorganize +and clean up the api. If you are using features that are not currently listed +in the :ref:`user_api` or :ref:`developer_api` documentation please open an issue. This will help +us to know what functions should be preserved, what requires a deprecation +prior to removal and which of our un-documented (non-public) features can +be removed without a deprecation. + + +.. _whats_new_2.15.1: + +2.15.1 +====== + +.. _whats_new_2.15.1_jsonschema: + jsonschema ----------