From 9c02a85837251a0acbc3765a0ef263078716a10d Mon Sep 17 00:00:00 2001 From: Cory Francis Myers Date: Mon, 13 Jun 2022 18:49:31 -0700 Subject: [PATCH] docs: Alembic migrations and tests must be self-contained --- .github/pull_request_template.md | 4 +++- README.md | 7 +++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e9c845e439..505661ad69 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -21,7 +21,9 @@ If these changes add or remove files other than client code, the AppArmor profil If these changes modify the database schema, you should include a database migration. Please check as applicable: - - [ ] I have written a migration and upgraded a test database based on `main` and confirmed that the migration applies cleanly + - [ ] I have written a migration and upgraded a test database based on `main` and confirmed that the migration is [self-contained] and applies cleanly - [ ] I have written a migration but have not upgraded a test database based on `main` and would like the reviewer to do so - [ ] I need help writing a database migration - [ ] No database schema changes are needed + +[self-contained]: https://github.com/freedomofpress/securedrop-client#generating-and-running-database-migrations diff --git a/README.md b/README.md index daf1876822..364abcfc72 100644 --- a/README.md +++ b/README.md @@ -270,6 +270,8 @@ alembic upgrade head alembic revision --autogenerate -m "describe your revision here" ``` +**NOTE.** Schema migrations, data migrations, and tests [MUST] be self-contained. That is, their `upgrade()` and `downgrade()` methods and their tests [MUST NOT] rely, directly or indirectly, on other project code, such as helper classes and functions defined outside of the migration under test, because these utilities may change in Git over time. (The scaffolding of the `test_alembic.py` test suite [MAY] rely on such utilities, because it is versioned at the Git level, not the Alembic level.) See [#1500](https://github.com/freedomofpress/securedrop-client/issues/1500) for an example of why this guideline applies. + ## AppArmor support An AppArmor profile is available for mandatory access control. When installing securedrop-client from a .deb package, the AppArmor profile will automatically be copied and enforced. Below are instructions to use the profile in non-production scenarios. @@ -406,3 +408,8 @@ Then you can use [`pdb` commands](https://docs.python.org/3/library/pdb.html#deb Logs can be found in the `{sdc-home}/logs`. If you are debugging a version of this application installed from a deb package in Qubes, you can debug issues by looking at the log file in `~/.securedrop_client/logs/client.log`. You can also add additional log lines in the running code in `/opt/venvs/securedrop-client/lib/python3.7/site-packages/securedrop_client/`. + + +[MAY]: https://datatracker.ietf.org/doc/html/rfc2119#section-5 +[MUST]: https://datatracker.ietf.org/doc/html/rfc2119#section-1 +[MUST NOT]: https://datatracker.ietf.org/doc/html/rfc2119#section-2