Merge pull request #495 from hed-standard/master

Create a release of HED Specification 3.1.0

CHANGELOG.md

@@ -0,0 +1,30 @@
+# CHANGELOG for HED specification
+
+## Changes for HED specification 3.1.0
+This release is focused on corrections and clarifications in the specification document
+and does not include any enhancements.
+
+* [**Clarification**] The inner tag group in a definition cannot be empty.
+* [**Clarification**] The additional tags within an `Onset` or `Offset` group must be
+enclosed in parentheses. Consequently, only one definition can anchor an event of temporal extent.
+* [**Correction/Clarification**] The initial specification said that definitions could be
+given anywhere. Our examples only put them in dummy entries in the sidecars.
+Allowing definitions to be anywhere turned out to be burdensome for downstream analysis
+tools. We have now restricted definitions so that they can only appear in dummy entries of sidecars.
+* [**Clarification**] Chapter 3.2 was rewritten so that full specification details of tag
+syntax were given and keyed to error codes in Appendix B.
+* [**Clarification**] Error codes of Appendix B were modified to have more consistent form,
+and some additional codes were added to account for requirements of the specification.
+* [**Improvement**] Each error code in Appendix B was given its own markdown section so that
+error messages in the validators could use the error code as a link into the specification
+for more information about the cause of errors.
+* [**Improvement**] A standardized set of validation test data keyed to the error codes 
+was added to the specification repository in the 
+[**error_tests**](https://github.com/hed-standard/hed-specification/tree/master/docs/source/_static/data/error_tests) directory. This test data will be validated by both the Python 
+and JavaScript validators in addition to their internal tests as part of the GitHub actions.
+* [**Clarification**] All chapters of the specification were edited for clarity and correctness.
+
+## Initial release 3.0.0 Oct. 27, 2022.
+
+The specification version was set to 3.0.0 to designate the specification for HED-3G
+corresponding to HED standard schema versions >= 8.0.0

README.md

@@ -4,15 +4,18 @@
 including information on the format and rules for HED vocabularies (schemas)
 as well as rules for how tools should treat HED-annotated data.
 
-If you just 
-want to annotate your data, please visit the [**HED resources**](https://www.hed-resources.org) documentation website. 
+If you just
+want to annotate your data, please visit the [**HED resources**](https://www.hed-resources.org/en/latest/index.html) documentation website. 
 If you are a developer of a new HED vocabulary (schema) please see the
-[**Schema development guide**](https://www.hed-resources.org/en/latest/HedSchemaDevelopmentGuide.html).
+[Schema development guide](https://www.hed-resources.org/en/latest/HedSchemaDevelopmentGuide.html).
 
 The latest version of the HED specification is available at the
 [**HED specification**](https://hed-specification.readthedocs.io/en/latest/index.html).
 
-The most current officially released version of the HED specification can be found at [HED specification (PDF)](<https://raw.githubusercontent.com/hed-standard/hed-specification/master/hedspec/HEDSpecification_3_0_0.pdf>`)
+The official library schemas are now housed on the
+[**hed-schemas**](https://github.com/hed-standard/hed-schemas) GitHub repository.
+
+The most current officially released version of the HED specification can be found at [**HED specification (PDF)**](<https://raw.githubusercontent.com/hed-standard/hed-specification/master/hedspec/HEDSpecification_3_0_0.pdf>`)
 
 ## About HED
 HED (Hierarchical Event Descriptors) is an evolving framework for the description and 
@@ -31,9 +34,9 @@ motion-capture, EKG, and audiovisual recording.
 
 The following white papers give an overview of HED and how it is used.
 
-> Robbins, K., Truong, D., Jones, A., Callanan, I., & Makeig, S. (2021). 
+> Robbins, K., Truong, D., Jones, A., Callanan, I., & Makeig, S. (2022). 
 > Building FAIR functionality: Annotating event-related imaging data using Hierarchical Event Descriptors (HED). 
-> Neuroinformatics Special Issue Building the NeuroCommons. Neuroinformatics https://doi.org/10.1007/s12021-021-09537-4. 
+> Neuroinformatics Special Issue Building the NeuroCommons. Neuroinformatics 20, pages463–481.
 > [https://link.springer.com/article/10.1007/s12021-021-09537-4](https://link.springer.com/article/10.1007/s12021-021-09537-4).
 
 > Robbins, K., Truong, D., Appelhoff, S., Delorme, A., & Makeig, S. (2021). 
@@ -48,9 +51,10 @@ The HED schema represents the allowed vocabulary for use in annotation.
 The HED specification document specifies how tools should implement 
 and validate various features of HED.
 
-| HED specification version | Release date | HED schema versions |
-| ----------------- | -------------------------- | -------------------------- |
-| HED Specification 3.0.0 | Oct 27, 2022 | >= HED 8.0.0 |
+| Specification<br>Version | Release date | Schema<br>versions | Description |
+| ---------- | ---------------- | -------------- | -------------- |
+| 3.0.0 | Oct 27, 2022 | &ge; 8.0.0 | - First official release |
+| 3.1.0 | Apr 5, 2023 | &ge; 8.0.0 | - Cleanup and clarification<br>- JSON unit tests keyed to errors. |
 
 The first official release of the HED specification, HED Specification 3.0.0, 
 marked the separation of the versioning of the specification and the schema.

docs/requirements.txt

@@ -1,25 +1,3 @@
-attrs>=21.4.0
-myst-parser>=0.17.2
-Pygments>=2.12.0
-click==8.1.3
-coverage==6.4.1
-defusedxml>=0.7.1
-et-xmlfile>=1.1.0
-Flask>=2.1.2
-Flask-WTF>=1.0.1
-inflect>=5.6.0
-itsdangerous>=2.1.2
-jdcal>=1.4.1
-Jinja2>=3.1.2
-MarkupSafe>=2.1.1
-portalocker>=2.4.0
-python-dateutil>=2.8.2
-pytz>=2022.1
-semantic_version>=2.10.0
-six>=1.16.0
-Sphinx>=4.5.0
-SphinxExtensions>=0.2.0
+Sphinx>=5.2.2
+myst-parser>=0.18.1
 sphinx_rtd_theme>=1.0.0
-Werkzeug>=2.1.2
-WTForms>=3.0.1
-xlrd>=2.0.1