Indentation, small edits

doc/operator-guide/schema-migration-process.rst

@@ -5,38 +5,28 @@ Schema Migration Process
 Add columns to sdm_schemas
 ==========================
 
-- Add the requested database additions, justifications, and where they are generated to (https://rubinobs.atlassian.net/wiki/spaces/DM/pages/246644760/Consolidated+Database+Non-EFD+Entries)
-- Create a ticket and edit the repository at https://sdm-schemas.lsst.io/ to apply your schema changes to any of the ``cdb_*.yml`` schemas.
-- If your ``sdm_schemas`` PR has issues, check that the schema conforms to Felis's data model and valid SQL tables can be created with ``felis validate/create`` (https://felis.lsst.io/user-guide/cli.html#felis-validate) using:
-- Alembic migrations should be automatically created by a git workflow after your ``sdm_schemas`` pull request completes.
+- Add the requested database additions, justifications, and where they are generated to our `confluence entry table <https://rubinobs.atlassian.net/wiki/spaces/DM/pages/246644760/Consolidated+Database+Non-EFD+Entries>`_.
+- Create a ticket and edit the repository at https://github.com/lsst/sdm_schemas to apply your schema changes to any of the ``cdb_*.yml`` schemas.
+- If your sdm_schemas PR has issues, check that the schema conforms to Felis's data model and valid SQL tables can be created with `felis validate/create <https://felis.lsst.io/user-guide/cli.html#felis-validate>`_
+- Alembic migrations should be automatically created by a git workflow after your sdm_schemas pull request completes.
 
 Create an Alembic Migration (manually)
 ======================================
 
 - Alembic (https://alembic.sqlalchemy.org/en/latest/front.html) keeps track of versioning by autogenerated migrations to sync the test stands and summit databases.
 - Versioning our database schema changes allows us to apply edits and move the database’s state forward or backward as needed.
 
-- How to create an Alembic migration to deploy your new ``sdm_schema`` edits:
-
-1. Create an Alembic migration on your ``consdb`` ticket branch.
-2. Use the script ``consdb/alembic-autogenerate.py`` to generate Alembic migrations. You’ll need the following environment variables:
-
-- ``SDM_SCHEMAS_DIR`` - Points to a local clone of ``sdm_schemas`` with your ``cdb_*`` schema changes.
-
-3. Run ``alembic-autogenerate`` to create version files in respective database-named directories in ``consdb``.
-
-- Follow the directions in the header of the script.
-
+1. Create an Alembic migration on your ConsDB ticket branch.
+2. Use the script ``consdb/alembic-autogenerate.py`` to generate Alembic migrations.
+3. Follow the directions in the header of the script, then run ``python alembic-autogenerate.py`` to create version files in respective database-named directories in ``consdb/alembic/``.
 4. Manually edit the generated files in ``consdb/alembic/<table-name>/`` to:
 
 - Remove the ``visit1`` and ``ccdvisit1`` views.
 - Ensure constraints and renamed columns are correct.
 
-
 Test alembic migration
 ======================
-
-- You will need to test the version migrating the TTS db using your ``consdb`` branch on before merging or applying the migration to the Summit.
+- You will need to test the version migrating the TTS db using your ConsDB branch on before merging or applying the migration to the Summit.
 - This testing should include testing any code that populates the new columns/tables at TTS/BTS if Summit schema is changing.
 
 1. Update the deployment on the test stand:
@@ -45,10 +35,10 @@ Test alembic migration
 - Choose the appropriate test stand (TTS, BTS)
 - Create a branch in ``phalanx`` and edit the corresponding test stand environment file ``phalanx/applications/consdb/values-<test stand>.yaml`` to point to your branch's built docker image (tickets-DM-###).
 - Coordinate and announce in the appropriate slack channel that you will begin testing your migrations.
-- Update the consdb deployment in ``<url.to.teststand>/argo-cd`` to use your ``phalanx`` branch in the ``Target Revision``. Refresh and check pod logs.
+- Update the ConsDB deployment in ``<url.to.teststand>/argo-cd`` to use your ``phalanx`` branch in the ``Target Revision``. Refresh and check pod logs.
 - Verify the tables that you will be upgrading exist using ``psql``
 - From the ``consdb/`` directory, (where ``alembic.ini`` file is) use the alembic commands to upgrade the existing database tables: ``alembic upgrade head -n <database name>``
-- Deploy new consdb software (``hinfo``, ``pqserver``) and check the initial logs.
+- Deploy new ConsDB software (``hinfo``, ``pqserver``) and check the initial logs.
 
 2. Test with LATISS imaging in ATQueue:
 ---------------------------------------
@@ -64,18 +54,19 @@ Test alembic migration
 3. ``take_image_latiss.py`` Update the configuration to remove anything that is not 'nimages' (1) and 'image_type' (BIAS or DARK or FLAT)
 
 - Once you have put these three scripts in the queue, click ``run``.
-- Watch for errors in the Script Queue and the ``argo-cd`` ``consdb`` pod logs and ``hinfo-latiss`` deployment.
+- Watch for errors in the Script Queue and the Argo-CD ConsDB pod logs and ``hinfo-latiss`` deployment.
 - Address any errors and retest.
 - Check the database by using ``psql`` commands like ``\dt`` to display the table names and maybe even ``SELECT * from cdb_latiss.exposure where day_obs == <YYYYMMDD>;`` to view the most recent data.
 
 - Run set_summary_state to set ATHeaderService and ATCamera back to STANDBY, and return LATISS back to STANDBY.
 - Then return these three scripts to their original configurations.
 
-- If you have encountered errors in this process, do not proceed to the summit, but address those errors and retest them with your ``phalanx`` branch pointing to your ``consdb`` branch with the updates that fix the errors.
+- If you have encountered errors in this process, do not proceed to the summit, but address those errors and retest them with your ``phalanx`` branch pointing to your ConsDB branch with the updates that fix the errors.
 
 
-- If tests are successful, create a pull request for the Alembic migration in ``consdb``. Tag the release according to ``standards-practices`` guidelines.
-- Update your existing phalanx branch to point the environment based deployments to this consdb tag. You are able to retest on the test stand at this point, hopefully there were no changes to your consdb pull request so this step is trivial.
+- If tests are successful, create a pull request for the Alembic migration in ConsDB. Tag the release according to ``standards-practices`` guidelines.
+- Update your existing phalanx branch to point the environment based deployments to this ConsDB tag.
+- You are able to retest on the test stand at this point, hopefully there were no changes to your ConsDB pull request so this step is trivial.
 
 
 Deploy migration in synchrony at Summit (if necessary), USDF, and Prompt Release (if necessary)
@@ -98,17 +89,17 @@ Deploy code to populate db at Summit and/or USDF
 - The CAP members may tell you a time frame that is acceptable for you to perform these changes.
 
 - They may also tell you specific people to coordinate with to help you take images to test LATISS and LSSTCOMCAMSIM tables. There will be more tables to test eventually.
-- Some important channels to note: #rubinobs-test-planning; #summit-announce; #summit-auxtel, https://obs-ops.lsst.io/Communications/slack-channel-usage.html.
+- Channels to note: #rubinobs-test-planning; #summit-announce; #summit-auxtel, https://obs-ops.lsst.io/Communications/slack-channel-usage.html.
 
-- When you get your final approval and designated time to perform the changes to ConsDb, announce on #summit-announce, and follow similar steps as test stand procedure above.
+- When you get your final approval and designated time to perform the changes to ConsDB, announce on #summit-announce, and follow similar steps as test stand procedure above.
 
 Summit Deployment Steps
 -----------------------
 
-1. Use a branch in ``phalanx`` to point to the ``consdb`` tag for deployment.
-2. Set the ``argo-cd`` application ``consdb's`` target revision to your ``phalanx`` branch.
-3. Refresh the consdb application and review pod logs.
+1. Use a branch in ``phalanx`` to point to the ConsDB tag for deployment.
+2. Set the Argo-CD application ``consdb's`` target revision to your ``phalanx`` branch.
+3. Refresh the ConsDB application and review pod logs.
 4. Have an image taken with the observing team, then verify database entries with a SQL query or Jupyter notebook.
 5. Check your new entries in the database using a jupyter notebook or SQL query in RSP showing your new image has been inserted to the database as expected.
 
-- Once deployment succeeds, set the ``Target Revision`` in ``argo-cd`` back to ``main`` and complete the ``phalanx`` PR for the tested ``consdb`` tag.
+- Once deployment succeeds, set the ``Target Revision`` in Argo-CD back to ``main`` and complete the ``phalanx`` PR for the tested ConsDB tag.

doc/user-guide/schemas.rst

@@ -29,18 +29,16 @@ Versioning
 - Should be consistent across all schemas, not just ConsDB
 
 major: backward incompatible changes to the database objects (adding a table, deleting a column)
-
-  - except adding a table is not backwards incompatible
+- except adding a table is not backwards incompatible
 
 minor: backward compatible changes to the database objects (adding a column)
 patch: updates or additions to semantics/metdata (units, UCDs, etc.)
-
-  - changing units can create incompatibilities
+- changing units can create incompatibilities
 
 And we should say what should happen in the case of changes to primary/foreign keys.
-Semantic neutrality: becoming non-primary is unique and anything becoming primary was already unique
+- Semantic neutrality: becoming non-primary is unique and anything becoming primary was already unique
 
-- or there can be ones that are not neutral.
+  - or there can be ones that are not neutral.
 
 Think about the utility of these versions in terms of interaction with the ConsDB APIs, migrations, etc.
 
@@ -51,5 +49,4 @@ So once ConsDB is available in TAP, it should be part of that set.
 
 What do users see, how does TAP play into this, do the schema need this type of micro versioning?
 
-
 - Services/cosndb repo versioning strategy - services of monthly YY.0M.DD