-
Notifications
You must be signed in to change notification settings - Fork 0
Backend Development Guide
This guide is on how to implement a feature for the backend, and covers all the steps from the issue to deploying changes.
Often you'll start working from an issue that has a lot of details about the feature & requirements, plus a person who you can ask questions to.
Implementing these features will often require creating endpoints to be accessed by the frontend. GET new.sfucsss.org/api/elections/by_name, for example. This means you'll need to add a new function to one of the urls.py files in a module.
An important consideration when making any endpoint is who should be allowed to access the data. You'll want to use the has_permission functions from the permission module, or make your own.
If you function stores data in the database, then testing is a bit more tricky. Regardless of the method, there's one main rule of thumb when testing: MANUALLY RUN EVERY ENDPOINT. Because this is python, your chances of making a mistake without the compiler catching it for you is very high, so it pays off 1000000% to make a point of running every endpoint at least once. Missing an await, for example, will be quite common.
In order for a database to be handled by the system it must extend Base from database.py, as follows.
from database import Base
# ...
class MyTable(Base):
# ...Once this is the case, you can set export LOCAL=true to enable the test database. You can now run python src/load_test_db.py to load the test database with to help test backend endpoints. You may wish to modify this file and custom data for your own testing purposes.
You'll be prompted with This will reset the postgresql+asyncpg:///test database, are you okay with this?. It's important that the string shown is the test (postgresql+asyncpg:///test) database. If you get an error instead, make sure you've configured and enabled the database according to https://github.com/CSSS/csss-site-backend/wiki/1.-Local-Setup.
By typing y and hitting enter, the database will be reset and updated with the new schema you've created, including all your test data.
This will reset the postgresql+asyncpg://localhost:5444/test database, are you okay with this? (y/N): y
Resetting DB...
successful connection test to postgresql+asyncpg://localhost:5444/test
found tables to delete: ['officer_info', 'alembic_version', 'site_user', 'user_session', 'officer_term']
deleted tables successfully
new tables: ['alembic_version', 'site_user', 'user_session', 'election_nominee', 'nominee_application', 'election', 'officer_term', 'officer_info']
login the 3 users, putting them in the site users table
add officer info
loading new sysadmin '<REDACTED>'
Done!However, while resetting the entire database is fine for local testing purposes, it won't work for a running service with a dynamically growing database. In order to deploy your changes you'll have to write an alembic database migration. This will include instructions on how to update the database schema and what to do with data that may already exist. For example, if you're adding a new non-nullable column to a table, you'll need to define a way to compute the entry or a default value.
TODO: instructions on how to do this.
You should create a draft PR the moment you make your first commit developing a feature. This allows you to ask questions and mention other developers inline. Once you're ready for a review, you can remove the draft status from your PR and request a review from someone.
Once the PR is reviewed it can be merged into main. However, it's not deployed yet!
In order for a PR to be deployed, csss-site-config (the parent repo) must update it's git submodule for csss-site-backend to point at the most recent commit to main. After this, the sysadmin or webmaster must ssh into the webserver and pull changes into csss-site-config, then run the deploy script.
In no longer than a minute, your changes should be live!