From 2fc379e09f66ddbde6c06947fa1b94dae1189990 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Wed, 12 May 2021 12:53:26 -0700 Subject: [PATCH] Prepare for 2.3.0 release (#475) --- .github/PULL_REQUEST_TEMPLATE.md | 13 +++ .github/PULL_REQUEST_TEMPLATE/release.md | 31 +++++++ core/nwb.file.yaml | 2 +- core/nwb.namespace.yaml | 2 +- docs/format/source/conf.py | 6 +- docs/format/source/format_release_notes.rst | 10 +-- docs/format/source/software_process.rst | 96 +++++++++++++++++++++ 7 files changed, 150 insertions(+), 10 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/PULL_REQUEST_TEMPLATE/release.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..7ebecf1e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,13 @@ +## Summary of changes + +- ... + +## PR checklist for schema changes + + +- [ ] 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` + + diff --git a/.github/PULL_REQUEST_TEMPLATE/release.md b/.github/PULL_REQUEST_TEMPLATE/release.md new file mode 100644 index 00000000..eda8a4b7 --- /dev/null +++ b/.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. diff --git a/core/nwb.file.yaml b/core/nwb.file.yaml index 5a649b03..e416964a 100644 --- a/core/nwb.file.yaml +++ b/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: diff --git a/core/nwb.namespace.yaml b/core/nwb.namespace.yaml index 77109e53..60b2552a 100644 --- a/core/nwb.namespace.yaml +++ b/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" diff --git a/docs/format/source/conf.py b/docs/format/source/conf.py index ba9d6bd9..15623f59 100644 --- a/docs/format/source/conf.py +++ b/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. diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst index 3815717a..4493320f 100644 --- a/docs/format/source/format_release_notes.rst +++ b/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``. diff --git a/docs/format/source/software_process.rst b/docs/format/source/software_process.rst index 99818fc8..ce132e79 100644 --- a/docs/format/source/software_process.rst +++ b/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 =============================