Prepare for release of NWB schema 2.8.0 (#597)

Author: rly

.github/PULL_REQUEST_TEMPLATE/release.md

@@ -11,8 +11,9 @@ Target release date: [date]
 - [ ] Update `docs/format/source/conf.py` as needed
 - [ ] Update release notes (set release date) in `docs/format/source/format_release_notes.rst` and any other docs as
   needed
-- [ ] Test docs locally (`cd docs/format; make fulldoc`) where the nwb-schema submodule in the local version of PyNWB
-  is fully up-to-date with the head of the dev branch.
+- [ ] Test docs locally (`cd docs/format; make fulldoc`) and check for warnings and errors
+- [ ] Ensure PyNWB and MatNWB have branches that have passing tests when using the head of the dev branch or this 
+  branch of nwb-schema
 - [ ] Push changes to this PR and make sure all PRs to be included in this release have been merged
 - [ ] Check that the readthedocs build for this PR succeeds (see auto-triggered PR build):
   https://readthedocs.org/projects/nwb-schema/builds/

.github/workflows/check_sphinx_links.yml

@@ -8,20 +8,18 @@ on:
 jobs:
   check-external-links:
     runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
     steps:
-      - name: Cancel non-latest runs
-        uses: styfle/cancel-workflow-action@0.11.0
-        with:
-          all_but_latest: true
-          access_token: ${{ github.token }}
-
-      - uses: actions/checkout@v4
+      - name: Checkout repo with submodules
+        uses: actions/checkout@v4
         with:
           submodules: 'recursive'
           fetch-depth: 0  # tags are required for versioneer to determine the version
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.12'
 
@@ -31,4 +29,4 @@ jobs:
           python -m pip install -r requirements-doc.txt
 
       - name: Check Sphinx links and references
-        run: sphinx-build -n -b linkcheck ./docs/format/source ./test_build
+        run: sphinx-build -n -W -b linkcheck ./docs/format/source ./test_build

.github/workflows/validate_schema.yml

@@ -1,21 +1,26 @@
 name: Validate schema
 
-on: [push, pull_request, workflow_dispatch]
+on:
+  push:
+    branches:
+      - dev
+  pull_request:
+  workflow_dispatch:
 
 jobs:
   validate:
-    # run pipeline on either a push event or a PR event on a fork
-    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python 3.12
-      uses: actions/setup-python@v4
-      with:
-        python-version: "3.12"
-    - name: Install dev branch of HDMF
-      run: |
-        pip install git+https://github.com/hdmf-dev/hdmf.git
-    - name: Validate schema specification
-      run: |
-        validate_hdmf_spec core -m nwb.schema.json
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dev branch of HDMF
+        run: pip install git+https://github.com/hdmf-dev/hdmf.git
+
+      - name: Validate schema specification
+        run: validate_hdmf_spec core -m nwb.schema.json

README.rst

@@ -8,16 +8,16 @@ To get started using NWB, please go to the `NWB overview website <https://nwb-ov
 This repo contains:
 
 * The core NWB schema
-* The `Documentation for the NWB schema <http://nwb-schema.readthedocs.io>`_ (editable `here <https://github.com/NeurodataWithoutBorders/nwb-schema/tree/dev/docs/format/source>`_)
+* The `Documentation for the NWB schema <https://nwb-schema.readthedocs.io>`_ (editable `here <https://github.com/NeurodataWithoutBorders/nwb-schema/tree/dev/docs/format/source>`_)
 * The `HDF5 storage specification <https://nwb-storage.readthedocs.io/en/latest/storage_hdf5.html>`_ (editable `here <https://github.com/NeurodataWithoutBorders/nwb-schema/blob/dev/docs/storage/source/storage_hdf5.rst>`_)
 
-The NWB schema uses the [NWB specification language](http://schema-language.readthedocs.io/),
+The NWB schema uses the [NWB specification language](https://schema-language.readthedocs.io/),
 which defines formal structures for describing the organization of
 complex data using basic concepts, e.g., Groups, Datasets, Attributes, and Links.
 
 For more information:
 
-- Learn more about NWB and `nwb.org <http://www.nwb.org/>`_.
+- Learn more about NWB and `nwb.org <https://www.nwb.org/>`_.
 - The PyNWB Python API for the NWB format is available on `Github <https://github.com/NeurodataWithoutBorders/pynwb>`_
 - The MatNWB Matlab API for the NWB format is available on `Github <https://github.com/NeurodataWithoutBorders/matnwb>`_
 

core/nwb.file.yaml

@@ -7,7 +7,7 @@ groups:
   attributes:
   - name: nwb_version
     dtype: text
-    value: "2.8.0-alpha"
+    value: "2.8.0"
     doc: File version string. Use semantic versioning, e.g. 1.2.1. This will be the
       name of the format with trailing major, minor and patch numbers.
   datasets:

core/nwb.namespace.yaml

@@ -57,4 +57,4 @@ namespaces:
   - doc: This source module contains neurodata_type for retinotopy data.
     source: nwb.retinotopy.yaml
     title: Retinotopy
-  version: "2.8.0-alpha"
+  version: "2.8.0"

docs/format/Readme.md

@@ -1,6 +1,6 @@
 **Overview**
 
-The NWB specification documentation uses Sphinx [http://www.sphinx-doc.org/en/stable/index.html](http://www.sphinx-doc.org/en/stable/index.html)
+The NWB specification documentation uses Sphinx [https://www.sphinx-doc.org/en/stable/index.html](https://www.sphinx-doc.org/en/stable/index.html)
 
 **Prerequisites**
 

docs/format/source/conf.py

@@ -83,9 +83,9 @@ def setup(app):
 # built documents.
 #
 # The short X.Y version.
-version = '2.8.0-alpha'
+version = '2.8.0'
 # The full version, including alpha/beta/rc tags.
-release = '2.8.0-alpha'
+release = '2.8.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -133,16 +133,12 @@ def setup(app):
 #html_theme = 'default'
 #html_theme = "sphinxdoc"
 html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
 
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
@@ -225,7 +221,7 @@ def setup(app):
 \setcounter{tocdepth}{3}
 \setcounter{secnumdepth}{6}
 \\usepackage{enumitem}
-\setlistdepth{100}
+\\setlistdepth{100}
 \\addto\\captionsenglish{\\renewcommand{\\contentsname}{Table of contents}}
 """,
 }

docs/format/source/credits.rst

@@ -5,7 +5,7 @@ Credits
 Acknowledgments
 ===============
 
-For details on the partners, members, and supporters of NWB please the http://www.nwb.org/ project website.
+For details on the partners, members, and supporters of NWB please the https://www.nwb.org/ project website.
 For specific contributions to the format specification and this document see the change logs of
 the Git repository at https://github.com/NeurodataWithoutBorders/nwb-schema .
 

docs/format/source/format_description.rst

@@ -17,9 +17,9 @@ The NWB format uses the following main primitives to hierarchically organize neu
   store metadata specific to the object they are associated with, and
 * A *Link* is a reference to another group or dataset.
 
-The NWB format is formally described via formal specification documents using the `NWB specification language <http://schema-language.readthedocs.io/en/latest/>`_ .
-HDF5 currently serves as the main format for storing data in the NWB format (see http://nwb-storage.readthedocs.io/en/latest/ for details).
-The `PyNWB <http://pynwb.readthedocs.io/en/stable/>`_ API is available to enable users to efficiently interact with NWB format files.
+The NWB format is formally described via formal specification documents using the `NWB specification language <https://schema-language.readthedocs.io/en/latest/>`_ .
+HDF5 currently serves as the main format for storing data in the NWB format (see https://nwb-storage.readthedocs.io/en/latest/ for details).
+The `PyNWB <https://pynwb.readthedocs.io/en/stable/>`_ API is available to enable users to efficiently interact with NWB format files.
 
 The NWB format uses a modular design in which all main semantic components of the format have
 a unique *neurodata_type* (similar to a Class in object-oriented design)(:numref:`sec_neurodata_type_intro`).
@@ -167,7 +167,7 @@ allowing users to extend (i.e., add to) existing and create new neurodata_types
 definitions for storing custom data. To avoid collisions between extensions,
 extensions are defined as part of custom namespaces (which typically import
 the core NWB namespace). Extensions to the format are written using the
-`Specification Language <http://schema-language.readthedocs.io/en/latest/>`_ .
+`Specification Language <https://schema-language.readthedocs.io/en/latest/>`_ .
 To ease development of extensions, the PyNWB_
 (and `HDMF <https://github.com/hdmf-dev/hdmf>`_ used by PyNWB) API provides dedicated
 data structures that support programmatic creation and use of extensions. An
@@ -214,7 +214,7 @@ All NWB Groups and Datasets with an assigned neurodata_type have three required
   namespace of an extension
 - ``object_id`` (variable-length string) is a universally unique identifier for this object within its hierarchy.
   It should be set to the string representation of a random UUID version 4 value
-  (see `RFC 4122 <https://tools.ietf.org/html/rfc4122>`_) upon first creation. It is **not** a hash of the data. Files
+  (see `RFC 4122 <https://datatracker.ietf.org/doc/html/rfc4122>`_) upon first creation. It is **not** a hash of the data. Files
   that contain the exact same data but were generated in different instances will have different ``object_id`` values.
   Currently, modification of an object does not require its ``object_id`` to be changed.
 

docs/format/source/format_release_notes.rst

@@ -3,16 +3,19 @@
 Release Notes
 =============
 
-2.8.0 (Upcoming)
-------------------------
+2.8.0 (November 24, 2024)
+-------------------------
 
-Minor changes
+Major changes
 ^^^^^^^^^^^^^
-- Added optional ``was_generated_by`` attribute to ``NWBFile`` to store provenance information (#578)
 - Deprecated ``EventWaveform`` neurodata type. (#584)
 - Deprecated ``ImageMaskSeries`` neurodata type. (#583)
+
+Minor changes
+^^^^^^^^^^^^^
+- Added optional ``was_generated_by`` attribute to ``NWBFile`` to store provenance information. (#578)
 - Made ``band_mean`` and ``band_std`` in ``DecompositionSeries`` optional. (#593)
-- Added ``Device.model_number``, ``Device.model_name``, ``Device.serial_number`` (#594)
+- Added ``Device.model_number``, ``Device.model_name``, ``Device.serial_number``. (#594)
 
 2.7.0 (February 7, 2024)
 ------------------------
@@ -686,7 +689,7 @@ types. To address this challenge, NWB 2.0 integrates ``UnitTimes``, ``ClusterWav
 into the new column-based table ``units/`` (i.e., ``intervals/units``) (which still uses the optimized vector data
 storage to efficiently store spike times). See for discussions and
 `I674 on PyNWB <https://github.com/NeurodataWithoutBorders/pynwb/issues/674>`_
-(and related `I675 on PyNWB <https://github.com/NeurodataWithoutBorders/pynwb/issues/675>`_) and the pull
+(and related `I239 on NWB Schema <https://github.com/NeurodataWithoutBorders/nwb-schema/issues/239>`_) and the pull
 request `PR684 on PyNWB <https://github.com/NeurodataWithoutBorders/pynwb/pull/684>`_ for detailed changes.
 
 

docs/storage/Readme.md

@@ -1,6 +1,6 @@
 **Overview**
 
-The NWB-N specification documentation uses Sphinx [http://www.sphinx-doc.org/en/stable/index.html](http://www.sphinx-doc.org/en/stable/index.html)
+The NWB specification documentation uses Sphinx [https://www.sphinx-doc.org/en/stable/index.html](https://www.sphinx-doc.org/en/stable/index.html)
 
 **Building the documentation**
 

docs/storage/source/conf.py

@@ -102,7 +102,6 @@
 #html_theme = 'default'
 #html_theme = "sphinxdoc"
 html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 def setup(app):
    app.add_css_file("theme_overrides.css")  # overrides for wide tables in RTD theme
@@ -112,9 +111,6 @@ def setup(app):
 # documentation.
 #html_theme_options = {}
 
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None

docs/storage/source/credits.rst

@@ -14,7 +14,7 @@ Oliver Ruebel and Andrew Tritt et al. in collaboration with the NWB community.
 Acknowledgments
 ===============
 
-For details on the partners, funders, and supporters of NWB please the http://www.nwb.org/ project website.
+For details on the partners, funders, and supporters of NWB please the https://www.nwb.org/ project website.
 For specific contributions to the format specification and this document see the change logs of
 the Git repository at https://github.com/NeurodataWithoutBorders/nwb-schema .
 

docs/storage/source/storage_description.rst

@@ -8,8 +8,8 @@ NWB Storage
 What is the role of data storage?
 =================================
 
-The `NWB format specification <http://nwb-schema.readthedocs.io/en/latest/index.html>`_
-defined using the `NWB specification language <http://schema-language.readthedocs.io/en/latest/index.html>`_
+The `NWB format specification <https://nwb-schema.readthedocs.io/en/latest/index.html>`_
+defined using the `NWB specification language <https://schema-language.readthedocs.io/en/latest/index.html>`_
 describes how to organize large collections of neuroscience data using
 basic primitives, e.g., Files, Groups, Datasets, Attributes, and Links to describe and hierarchically group data.
 The role of the data storage then is to store large collections of neuroscience data. In other words,