Merge pull request #1517 from freedomofpress/1500-squash-alembic

fix: squash Alembic migrations; eliminate non-self-contained data-migration tests

.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

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 `db.py`'s SQLAlchemy models or other 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