diff --git a/CHANGELOG.md b/CHANGELOG.md index 2de258f..ca315db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # NDX Catalog Changelog +## NDX Catalog 1.1.0 - July 26, 2024 + +- The Catalog is no longer rate-limited by the GitHub API. Records are pulled from the nwb-extensions GitHub organization every week, on pushes to this repo, and on demand. The website now displays those records instead of parsing records from the GitHub API on demand. Thanks to [@tuanpham96](https://github.com/tuanpham96) for his immensely helpful [contribution](https://github.com/nwb-extensions/nwb-extensions.github.io/pull/17). +- Replaced the extension sharing and versioning policies and proposal review process document that were cached on this site with links to the [nwb.org website](https://www.nwb.org/policies-overview/). +- Rendered safe Markdown from each extension's README. + ## NDX Catalog 1.0.0 - May 7, 2020 Initial release for: diff --git a/_includes/header.html b/_includes/header.html index 2572e82..bbe9712 100644 --- a/_includes/header.html +++ b/_includes/header.html @@ -25,13 +25,8 @@
  • Resources
    • diff --git a/_pages/docs.md b/_pages/docs.md deleted file mode 100644 index 170789d..0000000 --- a/_pages/docs.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "NDX Catalog Documentation" -layout: default -excerpt: "NDX Catalog Documentation" -sitemap: false -permalink: /docs ---- - -# Documentation - -**Coming Soon** - - diff --git a/_pages/news.md b/_pages/news.md index fb22a54..979a557 100644 --- a/_pages/news.md +++ b/_pages/news.md @@ -8,6 +8,11 @@ permalink: /news # News +## New version of the NDX Catalog released +**Date:** July 26, 2024 + +A new version of the NDX Catalog has been released, which is not rate-limited by the GitHub API. Thanks to [@tuanpham96](https://github.com/tuanpham96) for his immensely helpful [contribution](https://github.com/nwb-extensions/nwb-extensions.github.io/pull/17) to improve the Catalog. In addition, the extension sharing and versioning policies and proposal review process document have been moved to the [nwb.org website](https://www.nwb.org/policies-overview/). + ## Drafts released of NDX sharing guidelines, sharing strategies, and proposal review process **Date:** October 18, 2019 diff --git a/_pages/policies.md b/_pages/policies.md new file mode 100644 index 0000000..7dca9f0 --- /dev/null +++ b/_pages/policies.md @@ -0,0 +1,11 @@ +--- +title: "Guidelines and Policies" +layout: default +excerpt: "Guidelines and Policies" +sitemap: false +permalink: /policies +--- + +# Policies + +Please see the [nwb.org policies page](https://www.nwb.org/policies-overview/) for the latest guidelines and policies on sharing and versioning NWB extensions and proposing enhancements to the NWB core standard. \ No newline at end of file diff --git a/_pages/proposal_review.md b/_pages/proposal_review.md deleted file mode 100644 index a083968..0000000 --- a/_pages/proposal_review.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Proposal Review Process" -layout: default -excerpt: "Proposal Review Process" -sitemap: false -permalink: /proposal_review ---- - -# NWB Proposal Review Process - -* Version: 0.2.0 (DRAFT) -* Authors: - * Oliver Ruebel - * Andrew Tritt - * Benjamin Dichter - * Ryan Ly -* Last update: October 18, 2019 - -## Overview - -The purpose of this document is to define the process by which extensions to the NWB core standard are proposed, -evaluated, reviewed, and accepted. The goal is to facilitate community engagement while ensuring quality and utility -of the NWB data format. - -### Definitions - -* The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. -* **“Neurodata Extensions” (NDX)** refers to extensions to the NWB data standard. NDX MUST be described by a formal format specification using the NWB specification language. -* **“Internal NDX”** refers to extensions used within a particular lab, organization or project that are not intended for use outside of that group or context. -* **“Public NDX”** refers to extensions intended for use by the public (or specific larger community). -* **“Community Proposals”** refers to public NDX that are proposed to be integrated into the NWB core standard. -* **“NDX Catalog”** refers to the public catalog for NDX. The NDX Catalog is implemented via a dedicated public GitHub organization at [https://github.com/nwb-extensions](https://github.com/nwb-extensions) and website [https://nwb-extensions.github.io/](https://nwb-extensions.github.io/). -* **“ndx-custom** refers to the code repository used to manage the sources of the extension. This repository lives in the user's own Git space and is NOT part of the nwb-extensions organization. -* **“ndx-custom-record** refers to a specific record repository for deploying a particular extension as part of the NDX Catalog. This repo is part of the “nwb-extensions” GitHub organization. -* **“NWB Technical Advisory Board”** (TAB) is a high-level group of technical experts that reviews and plans technical activities regarding NWB. The TAB typically does not participate in day-to-day development activities but focuses on higher-level activities. -* **“NWB Executive Board”** (EB) is a group of scientists that supervises and coordinates NWB-related efforts, including development of NWB-related policies, funding, community outreach, and input for major technical decisions to the Technical Advisory Board. - -## Lifecycle of extensions - -Data standards are not static but evolve to adapt to changing requirements, clarify ambiguities, and fix bugs among others. The typical life-cycle of format extensions is outlined below. -NDX Lifecycle - -## Main stakeholders of NWB extensions and their roles in the extension lifecycle - -During active use of an extension, the main stakeholders of the extension include the developers of the extension, the NWB core development team, and the end-users using the extension. Review of extensions for acceptance to the NWB core data standard are led by the NWB Technical Advisory Board (TAB), the NWB Executive Board (EB), and the community review working group with comments, requests for changes, and updates provided by the other stakeholders (i.e., the extension developers, users, and the core developer team). -NDX Stakeholders - -## Phases of the review of extensions - -To guide and clearly communicate progress in the review and acceptance process, we use a multi-phased process for acceptance. As “Lab Extensions” have not entered the review process yet, they MAY either be internal or public NDX. NDX in review (i.e., NDX in any other phase than lab extension) MUST be public NDX. -NDX Review Phases - -## Process for creation, review and acceptance of extensions - -NDX Review Flowchart - -The flow-chart above illustrates the main process for creation, review, and acceptance of extensions as part of the NWB core data standard. The process begins with a development team creating a new extension. During initial development, this will often be an internal NDX. Once a working draft of the extension exists, the team will submit the extension to the NDX Catalog by creating a pull request on the staged-extensions repository. The NWB core development team tests compliance of the extension with NWB standards (typically via automated tests). Once accepted to the NDX Catalog, the extension becomes a public NDX with “Lab Extension” status. - -### The Community Proposal stage - -To initiate the review of the extension for integration with the NWB core, the creators/owners of the extension submit the extension for review to the NWB Technical Advisory Board (TAB). A proposal for creating a Community Proposal may be submitted to the TAB at any time and MUST contain a public NDX and SHOULD include basic drafts of the additional documents required for review. One (or more) members of the TAB will conduct an initial review of the proposal. At this point, the TAB may: 1) request changes to the proposal, or 2) accept the proposal for review. If the proposal is accepted for review, the TAB will initiate the community review process and create a working group that is responsible for leading the community review. The working group may consist of members of the TAB, EB, developers, users, and experts from the community. The developers of the extension MAY contribute to the working group to facilitate the review, but MUST NOT lead the review and decision-making process. - -At this point, the NDX is now a Community Proposal. The goal of the Community Proposal review phase is to complete the base technical review and associated review documents and to provide the community the opportunity to contribute to the review. All main review documents MUST be public via the NDX-custom-record repository to ensure the community can submit comments during the review. Comments and input are typically submitted directly as part of discussions of the working group or via GitHub issues and PRs on the NDX-custom-record repo (and NDX-custom repo if appropriate). - -As a result of the community review phase, the working group may: 1) request changes to the NDX to address issues identified in the review, 2) reject the proposal (so that the NDX would remain a regular lab extension), or 3) submit the proposal to the TAB for acceptance. - -### The NWB Core Proposal stage - -If the NDX is accepted by the TAB, the working group may submit a proposal for creating an NWB Core Proposal. This proposal MUST contain a public NDX and MUST include the completed review documents from the Community Proposal review. One (or more) members of the TAB will conduct an initial review of the proposal and may: 1) request changes, or 2) accept the proposal for review as an NWB Core Proposal. If accepted for review, the extension is now an official “NWB Core Proposal.” - -The “NWB Core Proposal” review phase is targeted at review of the technical merits and compliance with NWB standards and metrics. Depending on the results of this review, the TAB may decide to either: 1) reject the proposal (so that the NDX would remain a regular lab extension), 2) submit a request for changes to the working group (while, depending on the changes requested, either maintaining the core proposal status or changing status again to Community Proposal), or 3) accept the proposal and request integration with the NWB core. If deemed necessary, the TAB may also submit the proposal for approval to the NWB Executive Board (EB). The NWB community (including all users, developers, members of the NWN:N EB, TAB, and the broader community) may submit comments and requests for changes throughout the proposal review process. If accepted, the TAB will submit a request for integration of the extension to the NWB developer team. This is typically done by creating an issue on the corresponding repositories for the NWB core specification and APIs (e.g, PyNWB, MatNWB, nwb-schema, etc.). - -If the integration is successful, the extension becomes officially part of the NWB core standard. If issues are identified as part of the integration process with the core, the developer team may submit requests for changes by creating corresponding issues on the NDX-custom-record repository. The additional changes must be reviewed and approved by the TAB and the review documents updated accordingly. - -## Standards and metrics for review of NWB proposals - -To support the formal review and evaluation of extensions to be integrated into the NWB core, we will develop a set of format review documents, questionnaires, and a rating system to enable the community and working groups to evaluate critical quality metrics of extensions in a formal and reproducible manner. This will help guide the review process and help ensure compliance of extensions with key requirements of the NWB data standard. Some relevant quality metrics and standards include: - -1. **Rational**: Why do you want the extension and why should we (and others) want the extensions? - 1. **Precision**: Is the proposed extensions precise? i.e., can others easily understand what the extension is suggesting, the changes needed, and how it affects the current NWB standard? What changes are needed to the: (a) NWB data standard, (b) specification language, (c) storage backend, (d) APIs? - 1. **Significance**: Does the extension add significant functionality that is usable by a significantly large subset of end users? Who is the audience? Is this a general-purpose change? Does it affect one group of NWB users more than others? What other standards (if any) provide this feature? (e.g., if an extension serves only the use-cases of one (or very few) labs, then it should remain a public extension but not be integrated into the NWB core.) - 1. **Innovation**: Does the extension contribute to the innovation of the NWB data standard? Does the extension follow best-practices and lessons-learned for similar data from other communities? - 1. **Alternate reasoning**: What reasons could there be for not making the extension? There will be counterarguments and part of the job of the review is to find and evaluation these. Getting ahead of these early on provides an opportunity to put these in perspective. You may use the quality and compliance questions as a guide, e.g., Does the extension affect existing data/code? Is it hard to learn? Does it lead to demands for further extensions? Does it lead to larger or more complex files/APIs/codes? Does it require extensive implementation effort and support? Does the extension meet compliance and quality criteria? - 1. **Alternatives**: Are there alternative ways of providing the feature to serve the need? Are there alternative ways to use the extension (e.g., including possible unintended uses)? Are there possible attractive generalizations of the suggested scheme? -1. **Quality**: Does the extension meet important quality metrics? - 1. **Human interpretability**: Does the extension define data in a way that it is easily interpretable by humans? Ultimately, data shared via NWB MUST be usable by others. As such it is important that the data be defined in ways that are interpretable. - 1. **Usability**: Is the extension defined in ways that make it usable by others? Beyond interpretation of the data this includes questions of whether the extension addresses common use cases effectively. Also, what kind of data use and design styles does it support or prevent? Does it ease the design, implementation, or use of the data or APIs? How easy is the extension to document and teach (to novices and experts)? - 1. **Efficiency**: Does the extension define data in ways that the data can be stored, written, and accessed (and searched) in an efficient manner? What difference does the extension have on existing data/code (What does the data/code look like with/without the extensions? What is the effect of not doing the extension?) - 1. **Completeness**: Does the extension capture all data/metadata required for interpretation of the data and does it meet [FAIR principles](https://www.go-fair.org/fair-principles/)? - 1. **Maintainability**: Is the extension designed in a way that it is maintainable? In particular, we need to ensure that the design of the extension does not interfere with backward compatibility now and in the future. - 1. **Implementability**: Is the extension implementable on all reasonable target backends, APIs (programming languages), and hardware? Has the extension already been implemented (if so, has it been implemented in the exact form, and if not why do you expect results to carry over from “similar” implementations)? Has the implementation been used by anyone other than the implementers? Does the extension lead to demands for new support tools or API features? -1. **Compliance**: Is the extension compliant with the NWB standard and NWB principles? - 1. **Consistency**: Is the extension consistent with NWB (e.g., uses common naming conventions, reuses existing neurodata_types where possible, etc.). - 1. **Compatibility**: How does the extension affect compatibility with NWB? Does the extension break backwards compatibility of the NWB data standard? If so, how and why, and can the extension be changed to avoid (or at least minimize) compatibility issues? How does the extension affect existing data and codes? - 1. **Reusability**: Is the extension designed in a way that all (or important parts, e.g., neurodata_types) can be easily reused through the standard composition and inheritance mechanisms? - 1. **Uniqueness**: Does the extension add well-defined, unique capabilities to the NWB standard? e.g., is there overlap with functionality from existing features in the NWB core? If so, how can these overlaps be eliminated or minimized? Also, is there overlap with existing extensions and can/should a common extension be created to avoid the explosion of similar extensions and create a common standard. i.e., this process will require comparison of extension proposals with existing format components and proposals to avoid replication. The comparison process will be facilitated by the extension archive’s search, comparison, and suggestion tools. - -The above list is a collection of the kinds of questions developers and users will commonly ask. The list is not exhaustive and should be expanded to cover points relevant to the specific extension proposal. For points not relevant to the specific proposal ideally indicate that they are not applicable (and why). The list is intended to provide a helpful template and guideline for reviewing extensions, rather than a strict form. - -## Tools and methods for review - -The public review of NDX proposals for integration with the NWB core is facilitated by the NDX Catalog and the corresponding ndx-custom-record repository. As part of the review process, the reviewers will create and maintain review documents (in RST format) as part of a /review folder of the corresponding ndx-custom-record repository. Comments and requests for changes can in this way be submitted and processed via GitHub issues and pull requests on the ndx-custom-record repository. Requests for changes created as part of the review process can then be submitted to the developer team via issues on the corresponding ndx-custom repository (or email if no issue tracker is available for ndx-custom). The NDX Catalog further facilitates the review process by enabling reviewers to search and identify related extensions. For internal discussion, the review teams may also decide to use other mechanisms (e.g., Google Docs) to prepare review documents and track discussions; however, the main review documents MUST be made public via the ndx-custom-record repository so that they are available for public review. diff --git a/_pages/sharing_guidelines.md b/_pages/sharing_guidelines.md deleted file mode 100644 index 4dbc273..0000000 --- a/_pages/sharing_guidelines.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Sharing Guidelines" -layout: default -excerpt: "Sharing Guidelines" -sitemap: false -permalink: /sharing_guidelines ---- - -# Guidelines for sharing NWB extensions (NDX) -* Version: 0.3.0 (DRAFT) -* Authors: - * Oliver Ruebel - * Andrew Tritt - * Benjamin Dichter - * Ryan Ly -* Last update: October 18, 2019 - - -## Overview -The purpose of this document is to define the requirements and strategy for sharing format extensions for NWB, so called Neurodata Extensions (NDX). - -### Definitions - -* The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). -* **“Neurodata Extensions” (NDX)** refer to extensions to the NWB data standard. NDX MUST be described by a formal format specification using the NWB specification language. -* **“Internal NDX”** refer to extensions used within a particular lab, organization, or project that are not intended for use outside of that group or context. -* **“Public NDX”** refer to extensions intended for use by the public (or specific larger community). -* **“NDX Catalog”** refers to the public catalog for NDX. The NDX Catalog is implemented via a dedicated public GitHub organization at [https://github.com/nwb-extensions](https://github.com/nwb-extensions) and website [https://nwb-extensions.github.io/](https://nwb-extensions.github.io/). -* **“ndx-custom”** refers to a specific user extension repository that has usually been created from the ndx-template and is used to manage the sources of the extension. This repository lives in the user's own Git space and is NOT part of the nwb-extensions organization. -* **“ndx-custom-record”** refers to a specific record repository for deploying a particular extension as part of the NDX Catalog. This repo is part of the “nwb-extensions” GitHub organization. This repo is automatically generated by the CI of the staged-extensions repo and includes basic metadata about the NDX and information needed for install and deployment. - -## Requirements for sharing extensions -A Public NDX MUST follow the rules outlined below in order to be considered compliant. Internal NDX are also highly RECOMMENDED to follow the same rules outlined below as much as possible. - -1. Releases of extensions MUST minimally include: - 1. The complete YAML source and namespace files for the NDX, which MUST be compliant with the NWB specification language. In addition to “name”, and “schema”, the namespace specification further MUST include the “author”, “contact”, and “version” of the namespace. The version number MUST follow the NWB semantic versioning rules. - 1. LICENSE file detailing the license for the NDX. Permissive licenses SHOULD be used if possible. BSD license is RECOMMENDED. In particular for release via the NDX Catalog (see Sec. 4ii), the license MUST include language giving permission to members of the GitHub organization to distribute the extensions. - 1. Release notes detailing the changes between extension versions. Release notes MAY be included in the detailed RST documentation or as a separate RELEASENOTES.md (or .rst) file. - 1. Requirements file detailing dependencies on other NDX and where they can be installed from. This is required as the namespace.yaml only includes the names of namespaces that are being included. - 1. README.md (or .rst) file with an overview of what the NDX does and additional details about the NDX. -1. Releases of extensions SHOULD further include: - 1. The sources for generating the YAML specification using the PyNWB/HDMF extensions APIs. Sharing the sources eases maintenance, testing, and reuse of the NDX. - 1. Additional documentation in Sphinx RST format describing the NDX, credits, legal, and acknowledgements. - 1. Examples and tutorials describing the use of the extension. -1. Releases of extensions MAY further include: - 1. Custom Python plugins (e.g., Container classes for neurodata_types) for PyNWB. This is RECOMMENDED to make the NDX accessible to end users and has the advantage that custom functionality for interacting with the data can be defined. - 1. Custom Matlab plugins for MatNWB for representing neurodata_types. -1. Performing releases: - 1. To ensure compliance with the semantic versioning rules, public NDX MUST be released in a persistent fashion (i.e., sources of a particular version MUST not be modified after release and MUST remain accessible). - 1. Public NDX MUST register with the NDX Catalog. To register with the catalog, a public NDX MUST create an ndx-custom-record Git repository as part of the [nwb-extensions GitHub organization](https://github.com/nwb-extensions). An ndx-custom-record repo contains basic metadata about the NDX and information needed for install and deployment. The sources of the extension MAY be hosted in a different public ndx-custom repository. - 1. Public ndx-custom repositories SHOULD use Git tags to ensure compliance with (4i) and NDX SHOULD follow the NDX Catalog's sharing strategies. Note: software versions managed via Git tags MAY differ from the version of the extensions namespace. However, both MUST follow NWB semantic versioning rules. -1. Naming namespaces and repositories: - 1. The **name key** of the namespace for the extension SHOULD generally follow the following naming conventions: - 1. Start with the prefix “ndx-”, e.g., “ndx-cortical-surface” (required for registration with the NDX Catalog) - 1. Use short and descriptive names - 1. Use only lower-case ASCII letters (no special characters) - 1. Use “-” to separate different parts of the name (no spaces allowed) - 1. The **namespace YAML file** with the specification of the namespace SHOULD have the same name as the name key of the main namespace and the ``namespace.yaml`` postfix SHOULD be added. E.g., if the name of the namespace is "ndx-cortical-surface", then the YAML file would be called "ndx-cortical-surface.namespace.yaml". - 1. The **ndx-custom repository** of an extension SHOULD generally follow the following conventions: - 1. Have the same name as the name key of the main namespace of the NDX (i.e., “ndx_myname”)(e.g., “ndx-cortical-surface”) - 1. Use GitHub (preferred) or other public Git hosting service - 1. Include a description - 1. Specify at least the following GitHub topics: ndx-extension - 1. The Python package for the NDX SHOULD have the same name as the name key of the main namespace of the NDX, where hyphens are replaced with underscores (i.e., “ndx_myname”)(e.g., ``from ndx_cortical_surface import CorticalSurface``). - 1. The **ndx-custom-record repository** as part of the NDX Catalog MUST have the same name as the name key of the main namespace of the NDX i.e., “ndx-myname”)(e.g., “ndx-cortical-surface”). This strategy helps ensure that there are no name conflicts between public NDX namespace names. This repository is created automatically, so end users need not worry about this. diff --git a/_pages/sharing_strategies.md b/_pages/sharing_strategies.md deleted file mode 100644 index ea2828a..0000000 --- a/_pages/sharing_strategies.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -title: "NDX Sharing Strategies" -layout: default -excerpt: "NDX Sharing Strategies" -sitemap: false -permalink: /sharing_strategies ---- - -# Strategies for sharing NWB:N extensions (NDX) - -* Version: 0.3.1 (DRAFT) -* Authors: - * Oliver Ruebel - * Andrew Tritt - * Benjamin Dichter - * Ryan Ly -* Last update: October 18, 2019 - -## 1. Overview - -The purpose of this document is to define standard practices and strategies for sharing format extensions for NWB, so called Neurodata Extensions (NDX). - -### 1.1 Definitions - -* The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). -* **“Neurodata Extensions” (NDX)** refers to extensions to the NWB data standard. An NDX MUST be described by a formal format specification using the NWB specification language. -* **“Internal NDX”** refers to extensions used within a particular lab, organization, or project that are not intended for use outside of that group or context. -* **“Public NDX”** refers to extensions intended for use by the public (or specific larger community). -* **“NDX Catalog”** refers to the public catalog for NDX. The nwb-extensions catalog is implemented via a dedicated public GitHub organization at [https://github.com/nwb-extensions](https://github.com/nwb-extensions) and website [https://nwb-extensions.github.io/](https://nwb-extensions.github.io/). -* **“ndx-template”** refers to the repository containing a template for creating an extension from scratch. -* **“ndx-custom”** refers to a specific user extension repository that has usually been created from the ndx-template and is used to manage the sources of the extension. This repository lives in the user's own Git space and is NOT part of the nwb-extensions organization. -* **“staged-extensions”** repository refers to the GitHub repository that holds extension records awaiting review for registration of the extension with the catalog. It also contains a template for creating an extension record. -* **“ndx-custom-record”** refers to a specific record repository for deploying a particular extension as part of the NDX Catalog. This repo is part of the “nwb-extensions” GitHub organization. This repo is automatically generated by the CI of the staged-extensions repo and includes basic metadata about the NDX and information needed for install and deployment. -* **“user/ndx-custom-record”** refers to the user's fork of the ndx-custom-record repo. This repo lives in the users Git space (NOT in the nwb-extensions GitHub organization). - -### 1.2 Summary - -NWB defines a set of Versioning Guidelines for versioning extension namespaces and Sharing Guidelines that public NDX MUST follow and internal NDXs are highly RECOMMENDED to follow. In order to help ensure compliance with these rules, NWB provides a number of tools, templates, and guidelines. - -## 2. Methods and tools for sharing extensions - -### 2.1 [nwb-extensions](https://github.com/nwb-extensions): Extensions GitHub Organization - -NDXs are shared via a dedicated [nwb-extensions](https://github.com/nwb-extensions) GitHub organization for the NDX Catalog. The NDX Catalog provides the ndx-template and staged-extensions extension template repositories (see below) as well as all public ndx-custom-record repositories. In this way, all public extensions are managed in one place and MUST follow the same basic internal organization. The public ndx-custom-record repositories contain only metadata about the extensions, such as installation instructions and URLs to the extension sources. This strategy allows for labs, universities, and independent groups to maintain the source code for their extensions in their own Git space. The ability to do so can be important in particular when the developers of the extension are funded by their own grants and/or are applying for funding. - -#### 2.1.1 [ndx-template](https://github.com/nwb-extensions/ndx-template): Extension template - -The [ndx-template](https://github.com/nwb-extensions/ndx-template) provides a standard Git template repository with a standard setup for creating and sharing extensions and instructions for how to use the template. Using [Cookiecutter](https://cookiecutter.readthedocs.io/en/latest/), users can easily modify the template to create the basic setup for their ndx-template repository. See the [ndx-template](https://github.com/nwb-extensions/ndx-template) repository for details on the organization of the template. - -#### 2.1.2 [staged-extensions](https://github.com/nwb-extensions/staged-extensions): Creating custom ndx records - -The [staged-extensions](https://github.com/nwb-extensions/staged-extensions) repository is a place to submit new NDX records for registration with the NDX Catalog, i.e., before a ndx-custom-record repo exists for the extension. The repository holds an example record which should be copied and modified for a new extension to be registered. See the [staged-extensions](https://github.com/nwb-extensions/staged-extensions) repository for details on how to use the repo for registering extensions with the NDX Catalog. - -#### 2.2.3 ndx-custom-record: Custom extension catalog record - -The NDX Catalog contains a collection of ndx-custom-record repositories created by the creators of the extensions. See below for further details. - - -### 2.3 Custom Extension Code Repositories - -#### 2.3.1 ndx-custom-record: Custom extension catalog record - -The ndx-custom-record is created from the staged-extensions repository as part of the NDX catalog and MUST have the same name as the main namespace of the NDX. This strategy helps ensure that there are no name conflicts between public NDX namespace names. The ndx-custom-record repository MUST contain the following: - -* **/** : root directory of the repo - * **/ndx-meta.yaml**: REQUIRED YAML file with the metadata describing the extensions. The YAML file MUST contain a dict with the following keys: - * **name**: name of the namespace - * **version:** Semantic version number of the extension. See the Versioning Guidelines for details. - * **src: **: URL to the public repository with the sources of the extension - * **pip: **: URL for installing the extensions from PyPI - * **license**: License type - * **maintainers**: List of maintainers (GitHub usernames) for the extension - * **/README.(md|rst)** : REQUIRED readme with basic description of the extension, badges for CI, install instructions, etc. - * **/.gitignore**: Containing standard ignore options to ignore sphinx build files, autogenerated docs files from the nwb-docutils and sphinx, python and Matlab temporary files, etc. - -In addition the ndx-custom-record may contain the following OPTIONAL documents related to the review of the extensions: - - * **/review**: OPTIONAL folder with GitHub Markdown (or RST documents) related to the review of the extension for acceptance as part of the NWB core schema. - * If present the /review folder MUST contain: - * **/review/README.md** : Readme file with instructions on how to build and use the review docs and for linking all the documents together. - * **/review/RELEASE_NOTES.md** : Markdown file with the release notes for the review docs. This file MUST be linked to from README.md. - * **/review/REVIEW.md** : Main document with the review discussion for the NDX. This file MUST be linked to from README.md. - * In addition the folder MAY contain the following SUGGESTED documentation files: - * **/review/CREDITS.md** : Markdown file with the credits for the extension review. If present, the file MUST be linked to from the README.md. - * **/review/LEGAL.md** : Markdown file with the legal details about the extension review (e.g., license and copyright). If present, the file MUST be linked to from the README.md. - -#### 2.3.2 ndx-custom: Custom NWB Extensions -The ndx-custom repository contains the sources of the user extension that has usually been created from the ndx-template. This repository lives in the user's own Git space and is NOT part of the nwb-extensions organization. This provides users the ability to maintain ownership of the extension. - -### 2.4 Additional Tools and Methods - -#### 2.4.1 Documenting extensions - -The [nwb-docutils](https://github.com/NeurodataWithoutBorders/nwb-docutils) provide tools for generating Sphinx RST documentation directly from the YAML sources. The “generate_format_docs.py” command-line tools MUST be used to auto-generate documentation from the YAML sources. - -As part of the ndx-template Git repository, NWB provides a standard setup for generating Sphinx documentation for an extension based on the nwb-docutils. Extensions MAY customize the documentation but MUST follow the standard for building and generating the extensions. - -#### 2.4.2 Creating extension specifications - -Extensions SHOULD be created using the PyNWB specification API to improve maintainability of the extensions and to insulate the creators of the extensions from low-level details of the NWB specification language (see the PyNWB [docs](https://pynwb.readthedocs.io/en/stable/extensions.html) and [tutorial](https://pynwb.readthedocs.io/en/stable/tutorials/general/extensions.html#sphx-glr-tutorials-general-extensions-py) for details). The sources for creating the extensions SHOULD be shared along with the extension YAML specification files to facilitate maintenance and compliance with the NWB specification language. Extensions MAY also be created by just sharing YAML files (e.g., written by hand) that are compliant with the NWB specification language, however, this is NOT RECOMMENDED. The ndx-template includes dedicated locations for the YAML specification and sources, and includes a template Python file for implementing specifications using PyNWB. - -## 3. Extension process (create, deploy, update) - -The figure below illustrates the process for (1) creating a new extensions, (2) creating a record to register an extension with the extension catalog, and (3) to update an extension/record. The figure also illustrates the automated CI processes that are managed in the [nwb-extensions](https://github.com/nwb-extensions) catalog. The catalog process is modeled after the conda-forge model, enabling us to largely automate the catalog process using free, public services and avoid the need to host our own services. - -NDX Catalog Workflow - -### 3.1 Continuous Integration (CI) for Extensions - -This can be separated into CI for three main repositories: - -1. the staged-extensions repository as part of the NDX Catalog, -1. the ndx-custom-record repo as part of the NDX Catalog, and -1. the user's ndx-custom repository. - -Parts 1 and 2 are part of the NDX Catalog and are maintained by the NWB development team. Part 3 will need to be setup and maintained by the extension developers. The ndx-template can provide templates for defining CI for ndx-custom repositories, but ultimately this will be up to the extension developers to do. - -#### 3.1.1 staged-extensions CI - -For the staged-extensions repositories, we have common tests to validate basic compliance and working order of the extensions before creating the ndx-custom-record repo. Here we can test, e.g., the extensions metadata, i.e., are all required fields for the catalog specified and valid. - -#### 3.1.2 ndx-custom-record CI - -Similar to the staged-extensions, we can provide CI for ndx-custom-record repositories to automatically test compliance and working order of the extensions before merging pull requests. Here we can test, e.g., the extensions metadata, i.e., are all required fields for the catalog specified and valid. - -#### 3.1.3 ndx-custom CI - -Here we provide example configuration files and instructions (e.g., as part of the ndx-template repository), but ultimately this is up to the user to setup and maintain. The ndx-template repo itself will likely not include CI itself. However, it may include templates for setting up CI for ndx-custom user extension repositories. See the [ndx-template](https://github.com/nwb-extensions/ndx-template) repo for details. We generally recommend to use CI to: - -* Run unit tests (on all platforms) for API classes for the extension (and measure test coverage) -* Flake8 to ensure compliance with coding guidelines -* Test that YAML specifications are compliant with the specification language -* Test that sphinx documents (and galleries) can be built diff --git a/_pages/versioning_guidelines.md b/_pages/versioning_guidelines.md deleted file mode 100644 index f685eac..0000000 --- a/_pages/versioning_guidelines.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Versioning NDX" -layout: default -excerpt: "Versioning NDX" -sitemap: false -permalink: /versioning_guidelines ---- - -# Versioning NWB:N Specification Namespaces - -* Version: 0.3.0 (DRAFT) -* Authors: - * Oliver Ruebel -* Last update: April 9, 2020 - -## Overview - -The purpose of this document is to define the requirements and strategy for versioning namespaces for NWB:N extensions. - -### Definitions - -* The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). -* **“Neurodata Extensions” (NDX)** refer to extensions to he NWB:N data standard. NDX MUST be described by a formal format specification using the NWB:N specification language. -* **“Namespace”** is a declarative region for format extensions that provides a scope to the identifiers (the neurodata_types, groups, datasets, links, attributes etc.) inside it. Namespaces are used to organize format specifications into logical groups and to prevent name collisions that can occur especially when using multiple extensions to the core data specification. -* **“Sub-namespace”** refers to a namespace that is being used exclusively as a sub-component of an extension “Namespace.” I.e., sub-namespaces are always included in the main namespace and released in conjunction with the main namespace. Sub-namespaces can be useful if separate versioning of sub-components of a namespace is desirable. Generally we RECOMMEND to organize extensions into a single “Namespace” with possible multiple extension source yaml files, rather than using “Sub-namespaces” - -### Summary - -NWB:N uses semantic versioning for format specifications. Versions are assigned on a namespace level and are stored in the version key of the corresponding namespace.yaml file. A version number consists of the following components **MAJOR.MINOR.PATCH**. Version numbers should be incremented as follows: - -1. MAJOR version is incremented when adding incompatible schema changes, -2. MINOR version is incremented when functionality is added in a backwards-compatible manner (e.g., addition of new neurodata_types), -3. PATCH version is incremented when backwards-compatible bug fixes or other changes that do not affect the actual specification (e.g., correction of documentation etc.) -For public releases NWB:N does not allow custom extensions to the semantic versioning. Custom extensions (e.g., "-beta", "-rc") may be used internally on development branches but should be removed for full public release. - -## Versioning rules - -1. Extensions to NWB:N MUST contain a valid and complete specification of the namespace and all types via YAML files compliant with the NWB:N specification language. It is further RECOMMENDED that sources for generating the extensions via the PyNWB/HDMF specification tools also be released in conjunction with the extension. -2. A version number MUST take the form X.Y.Z. X, Y, and Z MUST be non-negative integers. X, Y, and Z MUST NOT contain leading zeroes. X identifies the major version, Y identifies the minor version, and Z identifies the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0. -3. Any modifications to a specification MUST be released as a new version. That is, once a specific version of a specification has been released, the contents of that version MUST NOT be modified -4. Initial version numbers SHOULD be created as follows: - - 1. For initial development, version numbers with a MAJOR version zero (i.e., 0.y.z) SHOULD be used indicating that anything may change at any time and that the extensions SHOULD not be considered stable. - 2. Version 1.0.0 defines the public API. Incrementation of version numbers thereafter MUST follow the semantic versioning rules outlined here. - -5. Version numbers MUST be incremented as follows: - - 1. PATCH version Z (x.y.Z where x > 0) MUST be incremented if only backwards compatible bug fixes or other changes that do not affect the actual specification (e.g., correction of documentation etc.) are introduced. Bug fix defines an internal change that does not affect the actual data format specification. The PATCH version MUST be reset to 0 when the MAJOR or MINOR version is incremented. - 2. MINOR version Y (x.Y.z where x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public specification. It MUST be incremented if any public API functionality is marked as deprecated and if new functionality or improvements are introduced. It MAY include patch level changes. The PATCH version MUST be reset to 0 when MINOR version is incremented. The MINOR version MUST be reset to 0 when the MAJOR version is incremented. - 3. MAJOR version X (X.y.z where X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public format specification. It MAY include minor and patch level changes. The PATCH and MINOR version MUST be reset to 0 when major version is incremented. - -6. Public releases format specification MUST NOT contain custom extensions to the semantic versioning. Custom extensions (e.g., "-beta", "-rc") MAY be used internally on development branches but MUST be removed for full public release. For internal releases, addition of a hyphen followed by lowercase alphabetic identifiers (a-z) SHOULD be used. Internal release additions SHOULD be comparable via standard alphabet ordering (e.g,. 1.0.0a < 1.0.0b). Typically, not the full spectrum of available alphabet characters are used for internal pre-releases, e.g., in the case of the following SUGGESTED internal versioning scheme: - - 1. The postfix **-alpha** (e.g., 2.0.1-alpha) may be used to indicate internal alpha releases. Internal alpha releases are considered not stable and under development. - 2. The postfix **-beta** (e.g., 2.0.1-beta) may be used to indicate internal beta releases. Internal beta releases are considered usable but still under development. - 3. The postfix **-rc** (e.g., 2.0.1-rc) may be used to indicate internal release candidates. Internal release candidate are considered usable and stable, expecting only minor changes for full public release. - -7. To support versioning of subcomponents of an extension, an extension MAY contain sub-namespaces that are included in the main extension namespace. Sub-namespaces MUST follow the same versioning rules outlined above. In addition the version of the main namespace (and any sub-namespaces that include a corresponding sub-namespace) MUST update their version numbers accordingly when the version of a sub-namespace is incremented. - -## Determining version precedence - -Version precedence refers to how versions are compared to each other when ordered. Precedence MUST be calculated by separating the version into MAJOR, MINOR, and PATCH (and for internal pre-release additional alphabetic identifiers) in that order. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: MAJOR, MINOR, and PATCH versions are always compared numerically. For example: 1.0.1 < 2.1.0 < 2.2.0 < 2.3.1. Versions with identical MAJOR and MINOR version are considered backward compatible, i.e., a file generated with version 2.0.x MUST be able to be read using all versions 2.0.y (y>=x). Internal pre-release additions to the versioning schema are considered to have lower precedence than regular versions (e.g., 2.0.0-alpha < 2.0.0, i.e., pre-release versions are considered lower than the same regular release version). Precedence for two pre-release versions with the same MAJOR, MINOR, and PATCH version SHOULD be determined by lexical comparison in ASCII sort order (i.e., comparison left-to-right in alphabetic order). E.g. 1.0.0-a < 1.0.0-b and for internal pre-release additions consisting of multiple letters 1.0.0-a < 1.0.0c < 1.0.0-ca < 1.0.0-cb < 1.0.0-d. - -## References - -The rules outlined in this document have been derived from [https://semver.org/](https://semver.org/) (2.0.0). - - - - -