NEXTSTEPS.md

Next Steps for ndx-spikesorting Extension for NWB

Creating Your Extension

1. In a terminal, change directory into the new ndx-spikesorting directory: cd ndx-spikesorting

2. Add any packages required by your extension to the [project] dependencies or [project.optional-dependencies] section of pyproject.toml.

3. Run python -m pip install -e . to install your new extension Python package and any other packages required to develop, document, and run your extension.

4. Modify src/spec/create_extension_spec.py to define your extension.

5. Run python src/spec/create_extension_spec.py to generate the spec/ndx-spikesorting.namespace.yaml and spec/ndx-spikesorting.extensions.yaml files.

6. Define API classes for your new extension data types.

   • As a starting point, src/pynwb/ndx_spikesorting/__init__.py includes an example for how to use the pynwb.get_class to generate a basic Python class for your new extension data type. This class contains a constructor and properties for the new data type.
   • Instead of using pynwb.get_class, you can define your own custom class for the new type, which will allow you to customize the class methods, customize the object mapping, and create convenience functions. See the Extending NWB tutorial for more details.

7. Define tests for your new extension data types in src/pynwb/ndx_spikesorting/tests or src/matnwb/tests. A test for the example TetrodeSeries data type is provided as a reference and should be replaced or removed.

   • Python tests should be runnable by executing pytest from the root of the extension directory. Use of PyNWB testing infrastructure from pynwb.testing is encouraged (see documentation).
   • Creating both unit tests (e.g., testing initialization of new data type classes and new functions) and integration tests (e.g., write the new data types to file, read the file, and confirm the read data types are equal to the written data types) is highly encouraged.
   • By default, to aid with debugging, the project is configured NOT to run code coverage as part of the tests. Code coverage reporting is useful to help with creation of tests and report test coverage. However, with this option enabled, breakpoints for debugging with pdb are being ignored. To enable this option for code coverage reporting, uncomment out the following line in your pyproject.toml: line

8. (Optional) Define custom visualization widgets for your new extension data types in src/pynwb/ndx_spikesorting/widgets so that the visualizations can be displayed with nwbwidgets. You will also need to update the vis_spec dictionary in src/pynwb/ndx_spikesorting/widgets/__init__.py so that nwbwidgets can find your custom visualizations.

9. You may need to modify pyproject.toml and re-run python -m pip install -e . if you use any dependencies.

10. Update the CHANGELOG.md regularly to document changes to your extension.

Documenting and Publishing Your Extension to the Community

1. Install the latest release of hdmf_docutils: python -m pip install hdmf-docutils

2. Start a git repository for your extension directory ndx-spikesorting and push it to GitHub. You will need a GitHub account.

   • Follow these directions: https://help.github.com/en/articles/adding-an-existing-project-to-github-using-the-command-line

3. Change directory into docs.

4. Run make html to generate documentation for your extension based on the YAML files.

5. Read docs/README.md for instructions on how to customize documentation for your extension.

6. Modify README.md to describe this extension for interested developers.

7. Add a license file. Permissive licenses should be used if possible. A BSD license is recommended.

8. Update the CHANGELOG.md to document changes to your extension.

9. Push your repository to GitHub. A default set of GitHub Actions workflows is set up to test your code on Linux, Windows, Mac OS, and Linux using conda; upload code coverage stats to codecov.io; check for spelling errors; check for style errors; and check for broken links in the documentation. For the code coverage workflow to work, you will need to set up the repo on codecov.io and uncomment the "Upload coverage to Codecov" step in .github/workflows/run_coverage.yml.

10. Make a release for the extension on GitHub with the version number specified. e.g. if version is 0.1.0, then this page should exist: https://github.com/h-mayorquin/ndx-spikesorting/releases/tag/0.1.0 . For instructions on how to make a release on GitHub see here.

11. Publish your updated extension on PyPI.

    • Follow these directions: https://packaging.python.org/en/latest/tutorials/packaging-projects/
    • You may need to modify pyproject.toml
    • If your extension version is 0.1.0, then this page should exist: https://pypi.org/project/ndx-spikesorting/0.1.0

    Once your GitHub release and pyproject.toml are ready, publishing on PyPI:

    python -m pip install --upgrade build twine
    python -m build
    twine upload dist/*

12. Go to https://github.com/nwb-extensions/staged-extensions and fork the repository.

13. Clone the fork onto your local filesystem.

14. Copy the directory staged-extensions/example to a new directory staged-extensions/ndx-spikesorting:

    cp -r staged-extensions/example staged-extensions/ndx-spikesorting

15. Edit staged-extensions/ndx-spikesorting/ndx-meta.yaml with information on where to find your NWB extension.

    • The YAML file MUST contain a dict with the following keys:

      • name: extension namespace name
      • version: extension version
      • src: URL for the main page of the public repository (e.g. on GitHub, BitBucket, GitLab) that contains the sources of the extension
      • pip: URL for the main page of the extension on PyPI
      • license: name of the license of the extension
      • maintainers: list of GitHub usernames of those who will reliably maintain the extension

    • You may copy and modify the following YAML that was auto-generated:

      name: ndx-spikesorting
      version: 0.1.0
      src: https://github.com/h-mayorquin/ndx-spikesorting
      pip: https://pypi.org/project/ndx-spikesorting/
      license: MIT
      maintainers: 
        - h-mayorquin

16. Edit staged-extensions/ndx-spikesorting/README.md to add information about your extension. You may copy it from ndx-spikesorting/README.md.

cp ndx-spikesorting/README.md staged-extensions/ndx-spikesorting/README.md

15. Add and commit your changes to Git and push your changes to GitHub.

cd staged-extensions
git add ndx-spikesorting
git commit -m "Add new catalog entry for ndx-spikesorting" .
git push

16. Open a pull request. Building of your extension will be tested on Windows, Mac, and Linux. The technical team will review your extension shortly after and provide feedback and request changes, if any.

17. When your pull request is merged, a new repository, called ndx-spikesorting-record will be created in the nwb-extensions GitHub organization and you will be added as a maintainer for that repository.

Updating Your Published Extension

1. Update your ndx-spikesorting GitHub repository.

2. Publish your updated extension on PyPI.

3. Fork the ndx-spikesorting-record repository on GitHub.

4. Open a pull request to test the changes automatically. The technical team will review your changes shortly after and provide feedback and request changes, if any.

5. Your updated extension is approved.