Merge branch 'main' of https://github.com/GSA/notifications-admin int…

…o 803-keep-current-service-visible

Makefile

@@ -15,7 +15,7 @@ NVMSH := $(shell [ -f "$(HOME)/.nvm/nvm.sh" ] && echo "$(HOME)/.nvm/nvm.sh" || e
 
 .PHONY: bootstrap
 bootstrap: generate-version-file ## Set up everything to run the app
-	poetry install
+	poetry install --sync
 	poetry run playwright install --with-deps
 	source $(NVMSH) --no-use && nvm install && npm ci --no-audit
 	source $(NVMSH) && npm run build
@@ -92,6 +92,18 @@ js-test: ## Run javascript unit tests
 fix-imports: ## Fix imports using isort
 	poetry run isort ./app ./tests
 
+.PHONY: py-lock
+py-lock: ## Syncs dependencies and updates lock file without performing recursive internal updates
+	poetry lock --no-update
+	poetry install --sync
+
+.PHONY: update-utils
+update-utils: ## Forces Poetry to pull the latest changes from the notifications-utils repo; requires that you commit the changes to poetry.lock!
+	poetry update notifications-utils
+	@echo
+	@echo !!! PLEASE MAKE SURE TO COMMIT AND PUSH THE UPDATED poetry.lock FILE !!!
+	@echo
+
 .PHONY: freeze-requirements
 freeze-requirements: ## create static requirements.txt
 	poetry export --without-hashes --format=requirements.txt > requirements.txt
@@ -101,7 +113,7 @@ pip-audit:
 	poetry requirements > requirements.txt
 	poetry requirements --dev > requirements_for_test.txt
 	poetry run pip-audit -r requirements.txt
-	-poetry run pip-audit -r requirements_for_test.txt
+	poetry run pip-audit -r requirements_for_test.txt
 
 .PHONY: audit
 audit: npm-audit pip-audit

README.md

@@ -73,6 +73,52 @@ The [Notify API](https://github.com/GSA/notifications-api) provides the UI's bac
 
 If you are using VS Code, there are also instructions for [running inside Docker](./docs/docker-remote-containers.md)
 
+### Python dependency management
+
+We're using [`Poetry`](https://python-poetry.org/) for managing our Python
+dependencies and local virtual environments.  When it comes to managing the
+Python dependencies, there are a couple of things to bear in mind.
+
+For situations where you manually manipulate the `pyproject.toml` file, you
+should use the `make py-lock` command to sync the `poetry.lock` file.  This will
+ensure that you don't inadvertently bring in other transitive dependency updates
+that have not been fully tested with the project yet.
+
+If you're just trying to update a dependency to a newer (or the latest) version,
+you should let Poetry take care of that for you by running the following:
+
+```
+poetry update <dependency> [<dependency>...]
+```
+
+You can specify more than one dependency together.  With this command, Poetry
+will do the following for you:
+
+- Find the latest compatible version(s) of the specified dependency/dependencies
+- Install the new versions
+- Update and sync the `poetry.lock` file
+
+In either situation, once you are finished and have verified the dependency
+changes are working, please be sure to commit both the `pyproject.toml` and
+`poetry.lock` files.
+
+### Keeping the notification-utils dependency up-to-date
+
+The `notifications-utils` dependency references the other repository we have at
+https://github.com/GSA/notifications-utils - this dependency requires a bit of
+extra legwork to ensure it stays up-to-date.
+
+Whenever a PR is merged in the `notifications-utils` repository, we need to make
+sure the changes are pulled in here and committed to this repository as well.
+You can do this by going through these steps:
+
+- Make sure your local `main` branch is up-to-date
+- Create a new branch to work in
+- Run `make update-utils`
+- Commit the updated `poetry.lock` file and push the changes
+- Make a new PR with the change
+- Have the PR get reviewed and merged
+
 ## To test the application
 
 From a terminal within the running devcontainer: