Update README.md

This commit is contained in:
zandercymatics 2024-05-08 10:17:20 -06:00
parent 3cf0792d15
commit d334f37293
No known key found for this signature in database
GPG key ID: FF4636ABEC9682B7

View file

@ -370,6 +370,13 @@ Per Django, signals "[...allow certain senders to notify a set of receivers that
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 events 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.
## Rules of use
When using signals, try to adhere to these guidelines:
1. Document its usage in this readme (or another centralized location), as well as briefly on the underlying class it is associated with. For instance, since the `handle_profile` directly affects the class `Contact`, the class description notes this and links to [signals.py](../../src/registrar/signals.py).
2. Where possible, avoid chaining signals together (i.e. a signal that calls a signal). If this has to be done, clearly document the flow.
3. Minimize logic complexity within the signal as much as possible.
4. Don't use signals when you can use another method, such as an override of `save()` or `__init__`.
### 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.
@ -398,11 +405,3 @@ This function is triggered by the post_save event on the User model, designed to
1. For New Users: Upon the creation of a new user, it checks for an existing `Contact` by email. If no matching contact is found, it creates a new Contact using the user's details from Login.gov. If a matching contact is found, it associates this contact with the user. In cases where multiple contacts with the same email exist, it logs a warning and associates the first contact found.
2. For Existing Users: For users logging in subsequent times, the function ensures that any updates from Login.gov are applied to the associated User record. However, it does not alter any existing Contact records.
## Rules of use
When using signals, try to adhere to these guidelines:
1. Document its usage in this readme (or another centralized location), as well as briefly on the underlying class it is associated with. For instance, since the `handle_profile` directly affects the class `Contact`, the class description notes this and links to [signals.py](../../src/registrar/signals.py).
2. Where possible, avoid chaining signals together (i.e. a signal that calls a signal). If this has to be done, clearly document the flow.
3. Minimize logic complexity within the signal as much as possible.
4. Don't use signals when you can use another method, such as an override of `save()` or `__init__`.