How to work with notification utils locally

How to work with notification-utils locally

notification-utils is a repo shared as a dependency between notification-admin and notification-api.

How to update notification-utils

1. Bump the version number in pyproject.toml (under [tool.poetry])
2. Update waffles: https://github.com/cds-snc/notification-utils/blob/main/.github/actions/waffles/requirements.txt
3. Push up your changes and do a PR review / merge as normal
4. Tag the merge commit with your new version:
   1. Checkout / update main
   2. Example: git tag -a 42.0.0 -m "42.0.0"
5. Push up the tag:
   1. git push origin --tags
6. Update pyproject.toml in notification-admin and notification-api with the new notification-utils version number

How to run notification-utils locally

Four methods:

• Install as a local dependency
• Modify virtualenv files directly
• As a mount in a devcontainer
• As a volume in a docker image

Install as a local dependency

Best when: You need to test code changes in both notification-admin and notification-api

Poetry allows you to install dependencies from local directories. This means we can change the code in our local notifications-utils repo, and then install that code directly into the admin and api projects to test before pushing anything to github.

Process

• Comment out the existing install in pyproject.toml. It looks like this: notifications-utils = {git = "https://github.com/cds-snc/notifier-utils.git", rev = "50.3.3"}

• Find the absolute path to your local notification-utils distribution file and add it as a line in pyproject.toml. Example: notifications-utils = { path = "file:///Users/USERNAME/Code/Notification/notification-utils/dist/notifications_utils-<version>.tar.gz" }

• Run poetry install

  • For good measure, use the --no-cache flag to ensure that Poetry doesn't pick up and use the utils version found in the cache
  • Alternatively, running poetry lock --no-update will update the poetry.lock file with the new locally specified dependency, updating the cache value. NOTE: if you take this route, make sure to revert and update the poetry.lock file again. Do not check in changes to the lock file if they contain this local reference to utils.

• When changes are made to notification_utils, run poetry build to regenerate the dist file, then run poetry install in dependent projects to update the changes.

Modify virtualenv files directly

Best when: You are only testing changes in one downstream repo (notification-admin or notification-api)

In VS Code, you can drill down into the definition of utils code, and it will bring you to the installed dependency files within your virtual environment. You can make changes to these files and they will be reflected in Notify.

You’ll need to copy any changes into your notification-utils local repo to commit / push.

As a mount in a devcontainer

Modify your devcontainer.json file to add :

"mounts": [
       "source=/Users/USERNAME/projects/notification-utils/dist,target=/nutils,type=bind,consistency=cached"
   ]

Now update pyproject.toml with the following: notifications-utils = { path = "/nutils/notifications_utils-<version>.tar.gz" }, and install the new dependency.

poetry install

As a volume in a docker image

Under Services -> Dev -> Volumes, add:

- /Users/USERNAME/projects/notification-utils/dist:/nutils:cached

Full example:

services:
 dev:
   build:
     context: ..
     dockerfile: .devcontainer/Dockerfile
   environment:
     SQLALCHEMY_DATABASE_URI: postgresql://USER:PW@db/notification_api
     SQLALCHEMY_DATABASE_TEST_URI: postgresql://USER:PW@db/test_notification_api
     REDIS_URL: redis://redis:6380
   volumes:
     - ..:/workspace:cached  
     - /Users/USERNAME/projects/notification-utils:/nutils:cached
  …

Now you can uninstall the current package and use this to install the new one:

poetry install

See this article for more details: https://code.visualstudio.com/remote/advancedcontainers/add-local-file-mount