Prepare for 2.3.0 release (#475)

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## Summary of changes
+
+- ...
+
+## PR checklist for schema changes
+
+<!-- If the current schema version already ends in "-alpha", then delete the first two items: -->
+- [ ] Update the version string in `docs/format/source/conf.py`, `core/nwb.namespace.yaml`, and `/core/nwb.file.yaml`
+  to the next version with the suffix "-alpha"
+- [ ] Add a new section in the release notes for the new version with the date "Upcoming"
+- [ ] Add release notes for the PR to `docs/format/source/format_release_notes.rst`
+
+<!-- See https://nwb-schema.readthedocs.io/en/latest/software_process.html for more details. -->

.github/PULL_REQUEST_TEMPLATE/release.md

@@ -0,0 +1,31 @@
+Prepare for release of nwb-schema [version]
+
+### Before merging:
+- [ ] Update requirements versions as needed
+- [ ] Update legal file dates and information in `Legal.txt`, `license.txt`, `README.md`, `docs/format/source/conf.py`,
+  and any other locations as needed
+- [ ] Update `README.rst` as needed
+- [ ] Update the version string in `docs/format/source/conf.py`, `common/namespace.yaml`, and `/core/nwb.file.yaml`
+  (remove "-alpha" suffix)
+- [ ] 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.
+- [ ] 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 (build latest to pull the new branch, then activate and
+  build docs for new branch): https://readthedocs.org/projects/nwb-schema/builds/
+
+### After merging:
+1. Create a new git tag. Pull the latest master branch locally, run `git tag [version] --sign`, copy and paste the
+   release notes into the tag message, and run `git push --tags`.
+2. On the [GitHub tags page](https://github.com/NeurodataWithoutBorders/nwb-schema/tags) page,
+   click "..." -> "Create release" for the new tag on the right side of the page.
+   Copy and paste the release notes into the release message, update the formatting if needed (reST to Markdown),
+   and set the title to the version string.
+3. Check that the readthedocs "latest" and "stable" builds run and succeed. Delete the readthedocs build for the
+   merged PR. https://readthedocs.org/projects/nwb-schema/builds/
+4. Update the nwb-schema submodule in the PyNWB branch corresponding to this schema version to point to the tagged
+   commit.
+
+See https://nwb-schema.readthedocs.io/en/latest/software_process.html for more details.

core/nwb.file.yaml

@@ -7,7 +7,7 @@ groups:
   attributes:
   - name: nwb_version
     dtype: text
-    value: "2.3.0-alpha"
+    value: "2.3.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.3.0-alpha"
+  version: "2.3.0"

docs/format/source/conf.py

@@ -76,16 +76,16 @@ def setup(app):
 
 # General information about the project.
 project = u'NWB Format Specification'
-copyright = u'2017-2020, Neurodata Without Borders'
+copyright = u'2017-2021, Neurodata Without Borders'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '2.3.0-alpha'
+version = '2.3.0'
 # The full version, including alpha/beta/rc tags.
-release = version
+release = '2.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/format/source/format_release_notes.rst

@@ -1,8 +1,8 @@
 Release Notes
 =============
 
-2.3.0 (May 11, 2021)
-----------------
+2.3.0 (May 12, 2021)
+---------------------
 
 - Add optional ``waveforms`` column to the ``Units`` table.
 - Add optional ``strain`` field to ``Subject``.
@@ -15,11 +15,11 @@ Release Notes
 - Set the ``stimulus_description`` for ``IZeroCurrentClamp`` to have the fixed value ``N/A``.
 - Update hdmf-common-schema from 1.1.3 to version 1.5.0.
   - The HDMF-experimental namespace was added, which includes the ``ExternalResources`` and ``EnumData``
-    data types. Schema in the HDMF-experimental namespace are experimental and subject to breaking changes at any time.
+  data types. Schema in the HDMF-experimental namespace are experimental and subject to breaking changes at any time.
   - Added experimental data type ``ExternalResources`` for storing ontology information / external resource references.
   - Added experimental data type ``EnumData`` to store data from a set of fixed values.
-  - Changed dtype for datasets within ``CSRMatrix`` from 'int' to 'uint' and added missing `data_type_inc: Container`
-    to the ``CSRMatrix`` type.
+  - Changed dtype for datasets within ``CSRMatrix`` from 'int' to 'uint' and added missing ``data_type_inc: Container``
+  to the ``CSRMatrix`` type.
   - Added data type ``SimpleMultiContainer``, a Container for storing other Container and Data objects together.
   - Added data type ``AlignedDynamicTable``, a DynamicTable type with support for categories (or sub-headings) each described by a separate DynamicTable.
   - Fixed missing dtype for ``VectorIndex``.

docs/format/source/software_process.rst

@@ -1,3 +1,99 @@
+Making a Pull Request
+=====================
+
+Actions to take on each PR that modifies the schema and does not prepare the schema for a public release
+(this is also in the `GitHub PR template`_):
+
+If the current schema version on "dev" is a public release, then:
+
+1. Update the version string in ``docs/format/source/conf.py`` and ``common/namespace.yaml`` to the next version with the
+   suffix "-alpha"
+2. Add a new section in the release notes for the new version with the date "Upcoming"
+
+Always:
+
+1. Add release notes for the PR to ``docs/format/source/format_release_notes.rst``
+
+Documentation or internal changes to the repo (i.e., changes that do not affect the schema files)
+do not need to be accompanied with a version bump or addition to the release notes.
+
+.. _`GitHub PR template`: https://github.com/NeurodataWithoutBorders/nwb-schema/blob/dev/.github/PULL_REQUEST_TEMPLATE.md
+
+
+Merging PRs and Making Releases
+===============================
+
+**Public release**: a tagged release of the schema. The version string MUST NOT have a suffix indicating a pre-release,
+such as "-alpha". The current "dev" branch of PyNWB and all PyNWB releases MUST point to a public release of
+nwb-schema. All schema that use nwb-schema as a submodule MUST also point only to public releases.
+
+**Internal release**: a state of the schema "dev" branch where the version string ends with "-alpha".
+
+The default branch of nwb-schema is "dev". **The "dev" branch holds the bleeding edge version of
+the nwb-schema specification.**
+
+PRs should be made to "dev". Every PR should include an update to ``docs/format/source/format_release_notes.rst``.
+If the current version is a public release, then the PR should also update the version of the schema in two places:
+``docs/format/source/conf.py`` and ``core/nwb.namespace.yaml``. The new version should be the next bugfix/minor/major version
+of the schema with the suffix "-alpha". For example, if the current schema on "dev" has version "2.2.0",
+then a PR implementing a bug fix should update the schema version from "2.2.0" to "2.2.1-alpha". Appending the "-alpha"
+suffix ensures that any person or API accessing the default "dev" branch of the repo containing an internal release
+of the schema receives the schema with a version string that is distinct from public releases of the schema. If the
+current schema on "dev" is already an internal release, then the version string does not need to be updated unless
+the PR requires an upgrade in the version (e.g., from bugfix to minor).
+
+PyNWB should contain a branch and PR that tracks the "dev" branch of nwb-schema. Before
+a public release of nwb-schema is made, this PyNWB branch should be checked to ensure that when the new release
+is made, the branch can be merged without issue.
+
+Immediately prior to making a new public release, the version of the schema should be updated to remove the "-alpha"
+suffix and the documentation and release notes should be updated as needed (see next section).
+
+The current "dev" branch of PyNWB and all PyNWB releases MUST always point to a public release of nwb-schema. If
+a public release contains an internally released version of nwb-schema, e.g., from an untagged commit on the
+"dev" branch, then it will be difficult to find the version (commit) of nwb-schema that was used to create
+an NWB file when the schema is not cached.
+
+Making a Release Checklist
+==========================
+
+Before merging:
+
+1. Update requirements versions as needed
+2. Update legal file dates and information in ``Legal.txt``, ``license.txt``, ``README.md``, ``docs/format/source/conf.py``,
+   and any other locations as needed
+3. Update ``README.rst`` as needed
+4. Update the version string in ``docs/format/source/conf.py``, ``core/nwb.namespace.yaml``, and ``/core/nwb.file.yaml``
+   (remove "-alpha" suffix)
+5. Update ``docs/format/source/conf.py`` as needed
+6. Update release notes (set release date) in ``docs/format/source/format_release_notes.rst`` and any other docs as needed
+7. 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.
+8. Push changes to a new PR and make sure all PRs to be included in this release have been merged. Add
+   ``?template=release.md`` to the PR URL to auto-populate the PR with this checklist.
+9. Check that the readthedocs build for this PR succeeds (build latest to pull the new branch, then activate and
+   build docs for new branch): https://readthedocs.org/projects/nwb-schema/builds/
+
+After merging:
+
+1. Create a new git tag. Pull the latest dev branch locally, run ``git tag [version] --sign``, copy and paste the
+   release notes into the tag message, and run ``git push --tags``.
+2. On the `GitHub tags`_ page, click "..." -> "Create release" for the new tag on the right side of the page.
+   Copy and paste the release notes into the release message, update the formatting if needed (reST to Markdown),
+   and set the title to the version string.
+3. Check that the readthedocs "latest" and "stable" builds run and succeed. Delete the readthedocs build for the
+   merged PR. https://readthedocs.org/projects/nwb-schema/builds/
+4. Update the nwb-schema submodule in the PyNWB branch corresponding to this schema version to point to the tagged commit.
+
+This checklist can also be found in the `GitHub release PR template`_.
+
+The time between merging this PR and creating a new public release should be minimized.
+
+.. _`GitHub tags`: https://github.com/NeurodataWithoutBorders/nwb-schema/tags
+.. _`GitHub release PR template`: https://github.com/NeurodataWithoutBorders/nwb-schema/blob/dev/.github/PULL_REQUEST_TEMPLATE/release.md
+
+
+
 The "dev" Branch and Releases
 =============================