From 5a027cad2b0390c5954031a19d08509259d76a7e Mon Sep 17 00:00:00 2001 From: rly Date: Tue, 9 Apr 2024 22:57:12 -0700 Subject: [PATCH 1/2] Add best practices section, prepare 3.0.0 release --- source/best_practices.rst | 43 +++++++++++++++++++++++++++++++++++++++ source/index.rst | 1 + source/release_notes.rst | 13 ++++++------ 3 files changed, 51 insertions(+), 6 deletions(-) create mode 100644 source/best_practices.rst diff --git a/source/best_practices.rst b/source/best_practices.rst new file mode 100644 index 0000000..5fe50db --- /dev/null +++ b/source/best_practices.rst @@ -0,0 +1,43 @@ +When writing schema using the HDMF Schema Language, including extensions, the HDMF development team provides a few best +practices to ensure correct behavior from the HDMF reference API and other APIs that we are aware of (e.g., MatNWB). + +1. Do not create schema that the HDMF reference API does not yet support. See `hdmf_support`_ for details. + +2. Define new data types (``data_type_def``) at the root of the schema rather than nested within another data type +definition. Nested type definitions may in some cases lead to errors in HDMF. See `hdmf#511`_ and `hdmf#73`_. + +3. Use the ``quantity`` key not in the data type definition but in the group/dataset spec where the type is included. +When the data type is included within another data type via ``data_type_inc``, if the ``quantity`` key omitted, the +default value of 1 would be used. This makes the ``quantity`` defined in the data type definition meaningless +and confusing. + +4. Use the ``name`` key not in the data type definition but in the group/dataset spec where the type is included, +unless you really want to require that all instances of the data type have that name. Mismatch between the name +defined on the data type definition and where it is included can lead to unexpected behavior in the APIs. + +5. Create a new data type when adding attributes/datasets/groups/links to an existing data type. See +`hdmf-schema-language#13`_ for details. Adding attributes/datasets/groups/links to an existing data type using +``data_type_inc`` is partially supported by the APIs, particularly the validator, so this is discouraged until +full, tested support is added. + +6. Modifying the dtype, shape, or quantity of a data type when using ``data_type_inc`` should only restrict the values +from their original definitions. This ensures that the data types follow the object-oriented programming principle of +inheritance. For example, if type A has ``dtype: text`` and type B extends type A +(``data_type_def: B, data_type_inc: A``), then type B should not redefine ``dtype`` to be ``int`` +which is incompatible with the ``dtype`` of type A. The same idea holds if type A is included in another type +and a new type is not defined (just ``data_type_inc: A``). +In other words, all children types should be valid against the parent type. See `hdmf#321`_. + +7. Non-scalar values for the ``value`` and ``default_value`` keys are not fully supported in the official APIs, +so these are discouraged until support is added. + +8. Do not put spaces in the names of data types or objects. This can lead to unexpected behavior in the APIs. +See `pynwb#1421`_ for an example. + + +.. _hdmf#511: https://github.com/hdmf-dev/hdmf/issues/511 +.. _hdmf#73: https://github.com/hdmf-dev/hdmf/issues/73 +.. _hdmf-schema-language#13: https://github.com/hdmf-dev/hdmf-schema-language/issues/13 +.. _hdmf#321: https://github.com/hdmf-dev/hdmf/issues/321 +.. _pynwb#1421: https://github.com/NeurodataWithoutBorders/pynwb/issues/1421 +.. _hdmf_support: https://hdmf.readthedocs.io/en/stable/spec_language_support.html diff --git a/source/index.rst b/source/index.rst index 648ba11..3982521 100644 --- a/source/index.rst +++ b/source/index.rst @@ -14,5 +14,6 @@ See the full language description, release notes, and credits below. :caption: Table of Contents description + best_practices release_notes credits diff --git a/source/release_notes.rst b/source/release_notes.rst index 641fe7b..2f3f6be 100644 --- a/source/release_notes.rst +++ b/source/release_notes.rst @@ -2,16 +2,17 @@ Release Notes ============= -Version 3.0.0 (Upcoming) +Version 3.0.0 (April 10, 2024) --------------------------------- * Deprecated the ``default_value`` and ``value`` keys for datasets. These keys are still supported for attributes. * Deprecated ``linkable`` key for groups and datasets. * First release as hdmf-schema-language. -* Remove legacy description of the `specs` or `spec` key. -* Add specification for the specification language used by each file. -* Add dtypes that are already supported in ``hdmf.spec``: short, uint64, bytes, and datetime. -* Clarify that if `name` is defined on a group/dataset/link specification, `quantity` may not be >1. -* Update ``datetime`` specification to allow a date with no time or timezone. +* Removed legacy description of the `specs` or `spec` key. +* Added specification for the specification language used by each file. +* Added dtypes that are already supported in ``hdmf.spec``: short, uint64, bytes, and datetime. +* Clarified that if `name` is defined on a group/dataset/link specification, `quantity` may not be >1. +* Updated ``datetime`` specification to allow a date with no time or timezone. +* Added best practices section to documentation. Version 2.0.2 (March, 2020) --------------------------------- From f223014095855dc9d35a9d467612693435f47df3 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Fri, 9 Aug 2024 10:31:10 -0700 Subject: [PATCH 2/2] Update release_notes.rst --- source/release_notes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/release_notes.rst b/source/release_notes.rst index 213f232..dbc7560 100644 --- a/source/release_notes.rst +++ b/source/release_notes.rst @@ -2,7 +2,7 @@ Release Notes ============= -Version 3.0.0 (August 26, 2024) +Version 3.0.0 (August 12, 2024) --------------------------------- * Deprecated the ``default_value`` key for datasets. This key is still supported for attributes. * Deprecated ``linkable`` key for groups and datasets.