zydronium/manage.get.gov
1
0
Fork 0
mirror of https://github.com/cisagov/manage.get.gov.git synced 2025-06-29 15:53:31 +02:00
Code Issues Projects Releases Packages Wiki Activity

Add documentation

Browse source
This commit is contained in:
zandercymatics 2024-05-08 09:37:23 -06:00
parent 8b2671e7f4
commit 9fefbf16c5
No known key found for this signature in database
GPG key ID: FF4636ABEC9682B7
1 changed files with 7 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

10
docs/developer/README.md
View file

@ -368,12 +368,14 @@ Though minimally, our application uses [Django signals](https://docs.djangoproje
Per Django, signals "[...allow certain senders to notify a set of receivers that some action has taken place.](https://docs.djangoproject.com/en/5.0/topics/signals/#module-django.dispatch)" For the vast majority of our use cases, [pre_save](https://docs.djangoproject.com/en/5.0/ref/signals/#pre-save) or [post_save](https://docs.djangoproject.com/en/5.0/ref/signals/#post-save) are be sufficient. Per Django, signals "[...allow certain senders to notify a set of receivers that some action has taken place.](https://docs.djangoproject.com/en/5.0/topics/signals/#module-django.dispatch)" For the vast majority of our use cases, [pre_save](https://docs.djangoproject.com/en/5.0/ref/signals/#pre-save) or [post_save](https://docs.djangoproject.com/en/5.0/ref/signals/#post-save) are be sufficient.
In other words, signals In other words, signals are a mechanism that allows different parts of an application to communicate with each other by sending and receiving notifications when said actions occur.
When an event occurs (such as creating, updating, or deleting a record) signals can automatically trigger specific actions in response. This allows different parts of an application to stay synchronized without tightly coupling the component.
### When should you use signals? ### When should you use signals?
Generally, you would use signals when you want an event to be synchronized across multiple areas of code at once (such as with two models or more models at once) in a way that would otherwise be difficult to achieve by overriding functions. Generally, you would use signals when you want an event to be synchronized across multiple areas of code at once (such as with two models or more models at once) in a way that would otherwise be difficult to achieve by overriding functions.
However, in most scenarios, if you can get away with not using signals - you should. However, in most scenarios, if you can get away with _not_ using signals - you should. The reasoning for this is that [signals give the appearance of loose coupling, but they can quickly lead to code that is hard to understand, adjust and debug](https://docs.djangoproject.com/en/5.0/topics/signals/#module-django.dispatch).
Consider using signals when: Consider using signals when:
1. Synchronizing events across multiple models or areas of code. 1. Synchronizing events across multiple models or areas of code.
@ -383,9 +385,11 @@ Consider using signals when:
5. (Rare) Offloading tasks when using multi-threading. 5. (Rare) Offloading tasks when using multi-threading.
### Where should you use them? ### Where should you use them?
This project compiles signals in a unified location to maintain readability. If you are adding a signal, you should always define them in [signals.py](../../src/registrar/signals.py). The reasoning for this is that [signals give the appearance of loose coupling, but they can quickly lead to code that is hard to understand, adjust and debug](https://docs.djangoproject.com/en/5.0/topics/signals/#module-django.dispatch). With the exception of rare circumstancee, this should be adhered to for the reasons mentioned above. This project compiles signals in a unified location to maintain readability. If you are adding a signal, you should always define them in [signals.py](../../src/registrar/signals.py). Except under rare circumstances, this should be adhered to for the reasons mentioned above.
### How are we currently using signals? ### How are we currently using signals?
At the time of writing, we currently only use signals for the Contact and User objects when synchronizing data returned from Login.gov. This is because the `Contact` object holds information that the user specified in our system, whereas the `User` object holds information that was specified in Login.gov.
To keep our signal usage coherent and well-documented, add to this document when a new function is added for ease of reference and use. To keep our signal usage coherent and well-documented, add to this document when a new function is added for ease of reference and use.
#### handle_profile #### handle_profile