Skip to content

Commit 2fc379e

Browse files
rlyrly
authored
Prepare for 2.3.0 release (#475)
1 parent 374cc29 commit 2fc379e

7 files changed

Lines changed: 150 additions & 10 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
## Summary of changes
2+
3+
- ...
4+
5+
## PR checklist for schema changes
6+
7+
<!-- If the current schema version already ends in "-alpha", then delete the first two items: -->
8+
- [ ] Update the version string in `docs/format/source/conf.py`, `core/nwb.namespace.yaml`, and `/core/nwb.file.yaml`
9+
to the next version with the suffix "-alpha"
10+
- [ ] Add a new section in the release notes for the new version with the date "Upcoming"
11+
- [ ] Add release notes for the PR to `docs/format/source/format_release_notes.rst`
12+
13+
<!-- See https://nwb-schema.readthedocs.io/en/latest/software_process.html for more details. -->

‎.github/PULL_REQUEST_TEMPLATE/release.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Prepare for release of nwb-schema [version]
2+
3+
### Before merging:
4+
- [ ] Update requirements versions as needed
5+
- [ ] Update legal file dates and information in `Legal.txt`, `license.txt`, `README.md`, `docs/format/source/conf.py`,
6+
and any other locations as needed
7+
- [ ] Update `README.rst` as needed
8+
- [ ] Update the version string in `docs/format/source/conf.py`, `common/namespace.yaml`, and `/core/nwb.file.yaml`
9+
(remove "-alpha" suffix)
10+
- [ ] Update `docs/format/source/conf.py` as needed
11+
- [ ] Update release notes (set release date) in `docs/format/source/format_release_notes.rst` and any other docs as
12+
needed
13+
- [ ] Test docs locally (`cd docs/format; make fulldoc`) where the nwb-schema submodule in the local version of PyNWB
14+
is fully up-to-date with the head of the dev branch.
15+
- [ ] Push changes to this PR and make sure all PRs to be included in this release have been merged
16+
- [ ] Check that the readthedocs build for this PR succeeds (build latest to pull the new branch, then activate and
17+
build docs for new branch): https://readthedocs.org/projects/nwb-schema/builds/
18+
19+
### After merging:
20+
1. Create a new git tag. Pull the latest master branch locally, run `git tag [version] --sign`, copy and paste the
21+
release notes into the tag message, and run `git push --tags`.
22+
2. On the [GitHub tags page](https://github.com/NeurodataWithoutBorders/nwb-schema/tags) page,
23+
click "..." -> "Create release" for the new tag on the right side of the page.
24+
Copy and paste the release notes into the release message, update the formatting if needed (reST to Markdown),
25+
and set the title to the version string.
26+
3. Check that the readthedocs "latest" and "stable" builds run and succeed. Delete the readthedocs build for the
27+
merged PR. https://readthedocs.org/projects/nwb-schema/builds/
28+
4. Update the nwb-schema submodule in the PyNWB branch corresponding to this schema version to point to the tagged
29+
commit.
30+
31+
See https://nwb-schema.readthedocs.io/en/latest/software_process.html for more details.

‎core/nwb.file.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ groups:
77
attributes:
88
- name: nwb_version
99
dtype: text
10-
value: "2.3.0-alpha"
10+
value: "2.3.0"
1111
doc: File version string. Use semantic versioning, e.g. 1.2.1. This will be the
1212
name of the format with trailing major, minor and patch numbers.
1313
datasets:

‎core/nwb.namespace.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,4 +57,4 @@ namespaces:
5757
- doc: This source module contains neurodata_type for retinotopy data.
5858
source: nwb.retinotopy.yaml
5959
title: Retinotopy
60-
version: "2.3.0-alpha"
60+
version: "2.3.0"

‎docs/format/source/conf.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -76,16 +76,16 @@ def setup(app):
7676

7777
# General information about the project.
7878
project = u'NWB Format Specification'
79-
copyright = u'2017-2020, Neurodata Without Borders'
79+
copyright = u'2017-2021, Neurodata Without Borders'
8080

8181
# The version info for the project you're documenting, acts as replacement for
8282
# |version| and |release|, also used in various other places throughout the
8383
# built documents.
8484
#
8585
# The short X.Y version.
86-
version = '2.3.0-alpha'
86+
version = '2.3.0'
8787
# The full version, including alpha/beta/rc tags.
88-
release = version
88+
release = '2.3.0'
8989

9090
# The language for content autogenerated by Sphinx. Refer to documentation
9191
# for a list of supported languages.

‎docs/format/source/format_release_notes.rst‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
Release Notes
22
=============
33

4-
2.3.0 (May 11, 2021)
5-
----------------
4+
2.3.0 (May 12, 2021)
5+
---------------------
66

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

‎docs/format/source/software_process.rst‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,99 @@
1+
Making a Pull Request
2+
=====================
3+
4+
Actions to take on each PR that modifies the schema and does not prepare the schema for a public release
5+
(this is also in the `GitHub PR template`_):
6+
7+
If the current schema version on "dev" is a public release, then:
8+
9+
1. Update the version string in ``docs/format/source/conf.py`` and ``common/namespace.yaml`` to the next version with the
10+
suffix "-alpha"
11+
2. Add a new section in the release notes for the new version with the date "Upcoming"
12+
13+
Always:
14+
15+
1. Add release notes for the PR to ``docs/format/source/format_release_notes.rst``
16+
17+
Documentation or internal changes to the repo (i.e., changes that do not affect the schema files)
18+
do not need to be accompanied with a version bump or addition to the release notes.
19+
20+
.. _`GitHub PR template`: https://github.com/NeurodataWithoutBorders/nwb-schema/blob/dev/.github/PULL_REQUEST_TEMPLATE.md
21+
22+
23+
Merging PRs and Making Releases
24+
===============================
25+
26+
**Public release**: a tagged release of the schema. The version string MUST NOT have a suffix indicating a pre-release,
27+
such as "-alpha". The current "dev" branch of PyNWB and all PyNWB releases MUST point to a public release of
28+
nwb-schema. All schema that use nwb-schema as a submodule MUST also point only to public releases.
29+
30+
**Internal release**: a state of the schema "dev" branch where the version string ends with "-alpha".
31+
32+
The default branch of nwb-schema is "dev". **The "dev" branch holds the bleeding edge version of
33+
the nwb-schema specification.**
34+
35+
PRs should be made to "dev". Every PR should include an update to ``docs/format/source/format_release_notes.rst``.
36+
If the current version is a public release, then the PR should also update the version of the schema in two places:
37+
``docs/format/source/conf.py`` and ``core/nwb.namespace.yaml``. The new version should be the next bugfix/minor/major version
38+
of the schema with the suffix "-alpha". For example, if the current schema on "dev" has version "2.2.0",
39+
then a PR implementing a bug fix should update the schema version from "2.2.0" to "2.2.1-alpha". Appending the "-alpha"
40+
suffix ensures that any person or API accessing the default "dev" branch of the repo containing an internal release
41+
of the schema receives the schema with a version string that is distinct from public releases of the schema. If the
42+
current schema on "dev" is already an internal release, then the version string does not need to be updated unless
43+
the PR requires an upgrade in the version (e.g., from bugfix to minor).
44+
45+
PyNWB should contain a branch and PR that tracks the "dev" branch of nwb-schema. Before
46+
a public release of nwb-schema is made, this PyNWB branch should be checked to ensure that when the new release
47+
is made, the branch can be merged without issue.
48+
49+
Immediately prior to making a new public release, the version of the schema should be updated to remove the "-alpha"
50+
suffix and the documentation and release notes should be updated as needed (see next section).
51+
52+
The current "dev" branch of PyNWB and all PyNWB releases MUST always point to a public release of nwb-schema. If
53+
a public release contains an internally released version of nwb-schema, e.g., from an untagged commit on the
54+
"dev" branch, then it will be difficult to find the version (commit) of nwb-schema that was used to create
55+
an NWB file when the schema is not cached.
56+
57+
Making a Release Checklist
58+
==========================
59+
60+
Before merging:
61+
62+
1. Update requirements versions as needed
63+
2. Update legal file dates and information in ``Legal.txt``, ``license.txt``, ``README.md``, ``docs/format/source/conf.py``,
64+
and any other locations as needed
65+
3. Update ``README.rst`` as needed
66+
4. Update the version string in ``docs/format/source/conf.py``, ``core/nwb.namespace.yaml``, and ``/core/nwb.file.yaml``
67+
(remove "-alpha" suffix)
68+
5. Update ``docs/format/source/conf.py`` as needed
69+
6. Update release notes (set release date) in ``docs/format/source/format_release_notes.rst`` and any other docs as needed
70+
7. Test docs locally (``cd docs/format; make fulldoc``) where the nwb-schema submodule in the local version of PyNWB
71+
is fully up-to-date with the head of the dev branch.
72+
8. Push changes to a new PR and make sure all PRs to be included in this release have been merged. Add
73+
``?template=release.md`` to the PR URL to auto-populate the PR with this checklist.
74+
9. Check that the readthedocs build for this PR succeeds (build latest to pull the new branch, then activate and
75+
build docs for new branch): https://readthedocs.org/projects/nwb-schema/builds/
76+
77+
After merging:
78+
79+
1. Create a new git tag. Pull the latest dev branch locally, run ``git tag [version] --sign``, copy and paste the
80+
release notes into the tag message, and run ``git push --tags``.
81+
2. On the `GitHub tags`_ page, click "..." -> "Create release" for the new tag on the right side of the page.
82+
Copy and paste the release notes into the release message, update the formatting if needed (reST to Markdown),
83+
and set the title to the version string.
84+
3. Check that the readthedocs "latest" and "stable" builds run and succeed. Delete the readthedocs build for the
85+
merged PR. https://readthedocs.org/projects/nwb-schema/builds/
86+
4. Update the nwb-schema submodule in the PyNWB branch corresponding to this schema version to point to the tagged commit.
87+
88+
This checklist can also be found in the `GitHub release PR template`_.
89+
90+
The time between merging this PR and creating a new public release should be minimized.
91+
92+
.. _`GitHub tags`: https://github.com/NeurodataWithoutBorders/nwb-schema/tags
93+
.. _`GitHub release PR template`: https://github.com/NeurodataWithoutBorders/nwb-schema/blob/dev/.github/PULL_REQUEST_TEMPLATE/release.md
94+
95+
96+
197
The "dev" Branch and Releases
298
=============================
399

0 commit comments

Comments
 (0)