From da4b29b28f2b09bd331571285c3ba0101f243f34 Mon Sep 17 00:00:00 2001 From: Ryan Ly Date: Wed, 1 Apr 2020 15:04:29 -0700 Subject: [PATCH] =?UTF-8?q?Update=20release=20process=20with=20notes=20abo?= =?UTF-8?q?ut=20coordinating=20with=20nwb-s=E2=80=A6=20(#1214)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update release process with notes about coordinating with nwb-schema * Update title * Add note about hdmf-common-schema --- docs/source/software_process.rst | 33 ++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/source/software_process.rst b/docs/source/software_process.rst index 3934b450f..6182fd3a4 100644 --- a/docs/source/software_process.rst +++ b/docs/source/software_process.rst @@ -96,3 +96,36 @@ by CircleCI, typically named `pynwb-{version}.tar.gz`. .. _versioneer: https://github.com/warner/python-versioneer .. _release: https://github.com/NeurodataWithoutBorders/pynwb/releases + +---------------------------------------------------- +Coordinating with nwb-schema Repository and Releases +---------------------------------------------------- + +The default branch is "dev". It is important that all releases of PyNWB contain a released version of nwb-schema. +If a release contains an unreleased version of nwb-schema, e.g., from an untagged commit on the "dev" branch, then +tracking the identity of the included nwb-schema becomes difficult and the same version string could point to two +different versions of the schema. + +Whenever the "dev" branch of the nwb-schema repo is updated, a commit should be made to the "schema_x.y.z" branch of +PyNWB, where "x.y.z" is the upcoming version of nwb-schema, that updates the nwb-schema submodule to the latest commit +of the "dev" branch on nwb-schema. If the update to nwb-schema is the first change after a release, the "schema_x.y.z" +branch should be created, the nwb-schema submodule should be updated, and a draft PR should be made for merging the +"schema_x.y.z" branch to "dev". This PR provides a useful public view into how the API changes with each change to the +schema. + +If the change in nwb-schema requires an accompanying change to PyNWB, then a new branch should be made with the +corresponding changes, and a new PR should be made for merging the new branch into the "schema_x.y.z" branch. The PR +should be merged in GitHub's "squash and merge" mode. + +When a new version of nwb-schema x.y.z is released, the "schema_x.y.z" branch of PyNWB should be checked to ensure +that the nwb-schema submodule points to the new release-tagged commit of nwb-schema. Then the PR should be merged +into dev with GitHub's "merge" mode. Commits should NOT be squashed because they will usually represent independent +changes to the API or schema, and the git history should reflect those changes separately. + +The "dev" branch should NEVER contain unreleased versions of nwb-schema to prevent cases of users and developers +accidentally publishing files with unreleased schema. This problem cannot be completely avoided, however, as users +could still publish files generated from the "schema_x.y.z" branch of PyNWB. + +The nwb-schema uses hdmf-common-schema. Changes in hdmf-common-schema that affect nwb-schema result in version +changes of nwb-schema and as such are managed in the same fashion. One main difference is that updates to +hdmf-common-schema may also involve updates to version requirements for HDMF in PyNWB.