Update version, readme, and software process for schema 1.2.0 (#38)

Author: rly

.github/PULL_REQUEST_TEMPLATE/release.md

@@ -8,7 +8,9 @@ Prepare for release of hdmf-common-schema [version]
 - [ ] Update the version string in `docs/source/conf.py` and `common/namespace.yaml` (remove "-alpha" suffix)
 - [ ] Update `docs/source/conf.py` as needed
 - [ ] Update release notes (set release date) in `docs/source/format_release_notes.rst` and any other docs as needed
-- [ ] Test docs locally (`make fulldoc`)
+- [ ] Test docs locally (`make fulldoc`). Note: if the schema has been changed, then the local copy of HDMF must contain
+  the latest changes in hdmf-common-schema in the git submodule in order for the schema changes to be reflected in the
+  docs.
 - [ ] Push changes to this PR and make sure all PRs to be included in this release have been merged
 - [ ] Point the HDMF submodule to this branch in the HDMF branch corresponding to this schema version and run HDMF tests
 - [ ] Check that the readthedocs build for this PR succeeds (build latest to pull the new branch, then activate and
@@ -17,5 +19,8 @@ Prepare for release of hdmf-common-schema [version]
 ### After merging:
 1. Create release on [GitHub releases page](https://github.com/hdmf-dev/hdmf-common-schema/releases) with release notes
 2. Check that the readthedocs "latest" and "stable" builds run and succeed
+3. A new version of HDMF should be released that uses the latest schema release and the schema readthedocs should be
+   rebuilt. Then schema changes will be reflected in the docs. This is due to a dependency between the docs and the
+   API.
 
 See https://hdmf-common-schema.readthedocs.io/en/latest/software_process.html for more details.

README.md

@@ -1,25 +1,27 @@
 # hdmf-common
 
-Documentation of the HDMF Common data format specification is available at [https://hdmf-common-schema.readthedocs.io](https://hdmf-common-schema.readthedocs.io/en/stable/)
+Documentation of the HDMF Common data format specification is available at
+[https://hdmf-common-schema.readthedocs.io](https://hdmf-common-schema.readthedocs.io/en/stable/)
 
 ## Description
 
-The HDMF Common specification, defines a collection of common, reusable data structures 
-that build the foundation for modeling of advanced data formats, e.g., [NWB](https://www.nwb.org/) 
+The HDMF Common specification defines a collection of common, reusable data structures
+that build the foundation for the modeling of advanced data formats, e.g., the
+[Neurodata Without Borders (NWB)](https://www.nwb.org/)
 neurophysiology data standard. The HDMF Common schema is integrated with [HDMF](https://github.com/hdmf-dev/hdmf),
-which provides advanced APIs for reading, writing, and using hdmf-common data types. 
+which provides advanced APIs for reading, writing, and using hdmf-common data types.
 
 The HDMF-common schema provides the following data structures:
 
 - **DynamicTable :** A column-based table data structure that supports ragged columns and one-to-one and one-to-many relationships
   - **VectorData :** A data structure for representing a column
-  - **VectorIndex :** A data structure for indexing a VectorData. This is used to store one-to-many relationships
+  - **VectorIndex :** A data structure for indexing a **VectorData**. This is used to store one-to-many relationships
   - **ElementIdentifiers :** A 1D array for storing primary identifiers for elements of a table
+  - **VocabData :** A data structure for representing a column where the data come from a controlled vocabulary of text values
 - **DynamicTableRegion :** A link from one table to an index or region of another
 - **CSRMatrix :** A compressed sparse row matrix
 
 The schema also provides the following base data structures:
 
 - **Data :** An abstract data type for a dataset
-- **Index :** An abstract pointer that indexes data values
 - **Container :** An abstract data type for a generic container storing collections of data and metadata

common/namespace.yaml

@@ -21,4 +21,5 @@ namespaces:
     title: Table data types
   - doc: data types for different types of sparse matrices
     source: sparse.yaml
-  version: 1.2.0-alpha
+    title: Sparse data types
+  version: 1.2.0

docs/source/conf.py

@@ -83,7 +83,7 @@ def setup(app):
 # built documents.
 #
 # The short X.Y version.
-version = 'v1.2.0-alpha'
+version = 'v1.2.0'
 # The full version, including alpha/beta/rc tags.
 release = version
 

docs/source/format_release_notes.rst

@@ -1,7 +1,7 @@
 hdmf-common Release Notes
 =========================
 
-1.2.0 (Upcoming)
+1.2.0 (July 10, 2020)
 ------------------------
 
 - Add software process documentation.

docs/source/software_process.rst

@@ -63,7 +63,9 @@ Before merging:
 4. Update the version string in ``docs/source/conf.py`` and ``common/namespace.yaml`` (remove "-alpha" suffix)
 5. Update ``docs/source/conf.py`` as needed
 6. Update release notes (set release date) in ``docs/source/format_release_notes.rst`` and any other docs as needed
-7. Test docs locally (``make fulldoc``)
+7. Test docs locally (``make fulldoc``). Note: if the schema has been changed, then the local copy of HDMF must contain
+   the latest changes in hdmf-common-schema in the git submodule in order for the schema changes to be reflected in the
+   docs.
 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. Point the HDMF submodule to this branch in the HDMF branch corresponding to this schema version and run HDMF tests
@@ -74,6 +76,9 @@ After merging:
 
 1. Create release on GitHub releases page with release notes
 2. Check that the readthedocs "latest" and "stable" builds run and succeed
+3. A new version of HDMF should be released that uses the latest schema release and the schema readthedocs should be
+   rebuilt. Then schema changes will be reflected in the docs. This is due to a dependency between the docs and the
+   API.
 
 This checklist can also be found in the `GitHub release PR template`_.