Developer documentation

Modifying the code or documentation

This is for changes that do not include schema changes. For schema changes see below.

Be sure to do all your work on a git branch off of main.

First, make sure you are in the SSS folder. If the SSS folder is in your home directory, you can get there by running cd to get to your home directory followed by cd SSS.
run git pull to get the latest code onto your machine
Make your changes.
Run pip install . to reinstall the package (unless you did a developer install using the -e flag to pip install in which case the installation always includes your latest changes).
Run pytest to check that all the tests pass. Fix any tests that fail. Reinstall the package as needed to use the new code (see step 4 above).
Add new tests as required to cover your changes and run them using pytest. See the test files in the tests folder for examples. Reinstall the package as needed to use the new code (see step 4 above).
Add and commit your changes to git. Push your commits to github.
Create a pull request on github to run all the continuous integration checks and to ask for a code review. Fix any errors in the continuous integration checks. When all the checks pass and you get an approving review, your changes can be integrated into main via the pull request.

Updating the database schema

Be sure to do all your work on a git branch off of main.

Adding or changing columns in an existing table

Update the table definition in the python file. Table definitions are class definitions that detail the columns (names, types, primary keys etc.).
Update any methods and/or scripts that interact with the table to account for your changes.
Run alembic revision --autogenerate -m '<version description>', replacing <version description> with a few words describing the change you’re making. This will create a new alembic revision file under the alembic directory in the repository that will reflect the changes to the database schema you just introduced. Inspect the resulting file carefully – alembic’s autogeneration is very clever but it’s certainly not perfect. It tends to make more mistakes with table or column alterations than with table creations.
Run alembic upgrade head to apply your schema changes and run pip install . to reinstall the package (unless you did a developer install using the -e flag to pip install in which case the installation always includes your latest changes).
Run pytest to check that all the tests pass. Fix any tests that fail. Reinstall the package as needed to use the new code (see step 4 above).
Add new tests as required to cover your changes and run them using pytest. See the test files in the tests folder for examples. Reinstall the package as needed to use the new code (see step 4 above).
Add and commit your changes to git, including the alembic version files that was created. Push your commits to github.
Create a pull request on github to run all the continuous integration checks and to ask for a code review. Fix any errors in the continuous integration checks. When all the checks pass and you get an approving review, your changes can be integrated into main via the pull request.

Adding a table

If appropriate, create a new python file under the sss directory. In rare cases it may make sense to define the table in an existing python file.
Create the table defintion. You can see some example table definitions in sss_table.py or geoid.py. Tables are defined as classes and their names should be in camel case (capital letters for the start of each word, lower case letters for the rest of the word, no underscores). The __tablename__ attribute is the name the table will have in the sql database. It should be all lower case with underscores between words.
Add an import of your new table class to the __init__.py file similar to the existing imports in that file.
Add methods and scripts as appropriate to interact with the new table. See the methods in sss_table.py, geoid.py and puma.py for examples. Script examples are in the scripts folders.
Run alembic revision --autogenerate -m '<version description>', replacing <version description> with a few words describing the change you’re making. This will create a new alembic revision file under the alembic directory in the repository that will reflect the changes to the database schema you just introduced. Inspect the resulting file carefully – alembic’s autogeneration is very clever but it’s certainly not perfect. It tends to make more mistakes with table or column alterations than with table creations.
Run alembic upgrade head to apply your schema changes and run pip install . to reinstall the package (unless you did a developer install using the -e flag to pip install in which case the installation always includes your latest changes).
Run pytest to check that all the tests pass. Fix any tests that fail. Reinstall the package as needed to use the new code (see step 5 above).
Add new tests as required to cover your changes and run them using pytest. If you created a python file for your changes, create a new test file to contain tests for your new table. See the test files in the tests folder for examples. Reinstall the package as needed to use the new code (see step 5 above).
Add and commit your changes to git, including the alembic version files that was created. Push your commits to github.
Create a pull request on github to run all the continuous integration checks and to ask for a code review. Fix any errors in the continuous integration checks. When all the checks pass and you get an approving review, your changes can be integrated into main via the pull request.