Merge pull request #69 from AllenNeuralDynamics/release-v0.12.0

Release v0.12.0

docs/source/Contributing.rst

@@ -0,0 +1,223 @@
+Contributor Guidelines
+======================
+
+This document will go through best practices for contributing to this
+project. We welcome and appreciate contributions or ideas for
+improvement.
+
+-  `Bug Reports and Feature
+   Requests <#bug-reports-and-feature-requests>`__
+-  `Local Installation for
+   Development <#local-installation-for-development>`__
+-  `Branches and Pull Requests <#branches-and-pull-requests>`__
+-  `Release Cycles <#release-cycles>`__
+
+Bug Reports and Feature Requests
+--------------------------------
+
+Before creating a pull request, we ask contributors to please open a bug
+report or feature request first:
+`issues <https://github.com/AllenNeuralDynamics/aind-data-access-api/issues/new/choose>`__
+
+We will do our best to monitor and maintain the backlog of issues.
+
+Local Installation for Development
+----------------------------------
+
+For development,
+
+-  For new features or non-urgent bug fixes, create a branch off of
+   ``dev``
+-  For an urgent hotfix to our production environment, create a branch
+   off of ``main``
+
+Consult the `Branches and Pull Requests <#branches-and-pull-requests>`__
+and `Release Cycles <#release-cycles>`__ for more details.
+
+From the root directory, run:
+
+.. code:: bash
+
+   pip install -e .[dev]
+
+to install the relevant code for development.
+
+Branches and Pull Requests
+--------------------------
+
+Branch naming conventions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Name your branch using the following format:
+``<type>-<issue_number>-<short_summary>``
+
+where:
+
+-  ``<type>`` is one of:
+
+   -  **build**: Changes that affect the build system
+      or external dependencies (e.g., pyproject.toml, setup.py)
+   -  **ci**: Changes to our CI configuration files and scripts
+      (examples: .github/workflows/ci.yml)
+   -  **docs**: Changes to our documentation
+   -  **feat**: A new feature
+   -  **fix**: A bug fix
+   -  **perf**: A code change that improves performance
+   -  **refactor**: A code change that neither fixes a bug nor adds
+      a feature, but will make the codebase easier to maintain
+   -  **test**: Adding missing tests or correcting existing tests
+   -  **hotfix**: An urgent bug fix to our production code
+-  ``<issue_number>`` references the GitHub issue this branch will close
+-  ``<short_summary>`` is a brief description that shouldn’t be more than 3
+   words.
+
+Some examples:
+
+-  ``feat-12-adds-email-field``
+-  ``fix-27-corrects-endpoint``
+-  ``test-43-updates-server-test``
+
+We ask that a separate issue and branch are created if code is added
+outside the scope of the reference issue.
+
+Commit messages
+~~~~~~~~~~~~~~~
+
+Please format your commit messages as ``<type>: <short summary>`` where
+``<type>`` is from the list above and the short summary is one or two
+sentences.
+
+Testing and docstrings
+~~~~~~~~~~~~~~~~~~~~~~
+
+We strive for complete code coverage and docstrings, and we also run
+code format checks.
+
+-  To run the code format check:
+
+.. code:: bash
+
+   flake8 .
+
+-  There are some helpful libraries that will automatically format the
+   code and import statements:
+
+.. code:: bash
+
+   black .
+
+and
+
+.. code:: bash
+
+   isort .
+
+Strings that exceed the maximum line length may still need to be
+formatted manually.
+
+-  To run the docstring coverage check and report:
+
+.. code:: bash
+
+   interrogate -v .
+
+This project uses NumPy’s docstring format: `Numpy docstring
+standards <https://numpydoc.readthedocs.io/en/latest/format.html>`__
+
+Many IDEs can be configured to automatically format docstrings in the
+NumPy convention.
+
+-  To run the unit test coverage check and report:
+
+.. code:: bash
+
+   coverage run -m unittest discover && coverage report
+
+-  To view a more detailed html version of the report, run:
+
+.. code:: bash
+
+   coverage run -m unittest discover && coverage report
+   coverage html
+
+and then open ``htmlcov/index.html`` in a browser.
+
+Pull Requests
+~~~~~~~~~~~~~
+
+Pull requests and reviews are required before merging code into this
+project. You may open a ``Draft`` pull request and ask for a preliminary
+review on code that is currently a work-in-progress.
+
+Before requesting a review on a finalized pull request, please verify
+that the automated checks have passed first.
+
+Release Cycles
+--------------------------
+
+For this project, we have adopted the `Git
+Flow <https://www.gitkraken.com/learn/git/git-flow>`__ system. We will
+strive to release new features and bug fixes on a two week cycle. The
+rough workflow is:
+
+Hotfixes
+~~~~~~~~
+
+-  A ``hotfix`` branch is created off of ``main``
+-  A Pull Request into is ``main`` is opened, reviewed, and merged into
+   ``main``
+-  A new ``tag`` with a patch bump is created, and a new ``release`` is
+   deployed
+-  The ``main`` branch is merged into all other branches
+
+Feature branches and bug fixes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  A new branch is created off of ``dev``
+-  A Pull Request into ``dev`` is opened, reviewed, and merged
+
+Release branch
+~~~~~~~~~~~~~~
+
+-  A new branch ``release-v{new_tag}`` is created
+-  Documentation updates and bug fixes are created off of the
+   ``release-v{new_tag}`` branch.
+-  Commits added to the ``release-v{new_tag}`` are also merged into
+   ``dev``
+-  Once ready for release, a Pull Request from ``release-v{new_tag}``
+   into ``main`` is opened for final review
+-  A new tag will automatically be generated
+-  Once merged, a new GitHub Release is created manually
+
+Pre-release checklist
+~~~~~~~~~~~~~~~~~~~~~
+
+-  ☐ Increment ``__version__`` in
+   ``src/aind_data_access_api/__init__.py`` file
+-  ☐ Run linters, unit tests, and integration tests
+-  ☐ Verify code is deployed and tested in test environment
+-  ☐ Update examples
+-  ☐ Update documentation
+
+   -  Run:
+
+   .. code:: bash
+
+      sphinx-apidoc -o docs/source/ src
+      sphinx-build -b html docs/source/ docs/build/html
+
+-  ☐ Update and build UML diagrams
+
+   -  To build UML diagrams locally using a docker container:
+
+   .. code:: bash
+
+      docker pull plantuml/plantuml-server
+      docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
+
+Post-release checklist
+~~~~~~~~~~~~~~~~~~~~~~
+
+-  ☐ Merge ``main`` into ``dev`` and feature branches
+-  ☐ Edit release notes if needed
+-  ☐ Post announcement

docs/source/ExamplesDocDBDirectConnection.rst

@@ -1,5 +1,5 @@
 Examples - DocDB Direct Connection
-==========
+==================================
 
 This page provides examples for interact with the Document Database (DocDB)
 using the provided Python client.
@@ -12,7 +12,7 @@ Querying Metadata
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Count Example 1: Get # of records with a certain subject_id
-------------------
+-----------------------------------------------------------
 
 .. code:: python
 
@@ -30,7 +30,7 @@ Count Example 1: Get # of records with a certain subject_id
       print(count)
 
 Filter Example 1: Get records with a certain subject_id
-------------------
+-------------------------------------------------------
 
 .. code:: python
 
@@ -62,7 +62,7 @@ With projection (recommended):
 
 
 Filter Example 2: Get records with a certain breeding group
-------------------
+-----------------------------------------------------------
 
 .. code:: python
 
@@ -97,7 +97,7 @@ With projection (recommended):
       print(json.dumps(records, indent=3))
 
 Aggregation Example 1: Get all subjects per breeding group
-------------------
+----------------------------------------------------------
 
 .. code:: python
 

docs/source/UserGuide.rst

@@ -12,7 +12,7 @@ We have two primary databases:
 2. A `relational database <#rds-tables>`__ to store structured tables.
 
 Document Database (DocDB)
---------------------
+-------------------------
 
 AIND metadata records stored in the DocDB describe the ``metadata.nd.json``
 for a data asset:
@@ -66,7 +66,7 @@ REST API (Read-Only)
    filter = {"subject.subject_id": "123456"}
    limit = 1000
    paginate_batch_size = 100
-   response = docdb_api_client.retrieve_data_asset_records(
+   response = docdb_api_client.retrieve_docdb_records(
       filter_query=filter,
       limit=limit,
       paginate_batch_size=paginate_batch_size
@@ -75,14 +75,14 @@ REST API (Read-Only)
 
 
 Direct Connection (SSH) - Database UI (MongoDB Compass)
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 MongoDB Compass is a database GUI that can be used to query and interact
 with our document database.
 
 To connect:
 
-1. If provided a temporary SSH password, please first run ``ssh {ssh-username}@54.184.81.236``
+1. If provided a temporary SSH password, please first run ``ssh {ssh-username}@{ssh_host}``
    and set a new password.
 2. Download the full version of `MongoDB Compass <https://www.mongodb.com/try/download/compass>`__.
 3. When connecting, click “Advanced Connection Options” and use the configurations below.
@@ -141,7 +141,7 @@ To connect:
    )
 
 Direct Connection (SSH) - Python Client
-~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We have some convenience methods to interact with our Document Store.
 You can create a client by explicitly setting credentials, or downloading from AWS Secrets Manager.

docs/source/index.rst

@@ -13,6 +13,7 @@ Welcome to this repository's documentation!
 
    UserGuide
    ExamplesDocDBDirectConnection
+   Contributing
    modules
 
 

src/aind_data_access_api/__init__.py

@@ -1,3 +1,3 @@
 """Init package"""
 
-__version__ = "0.11.0"
+__version__ = "0.12.0"