diff --git a/docs/developer/README.md b/docs/developer/README.md index d0a8be136..d293abf5b 100644 --- a/docs/developer/README.md +++ b/docs/developer/README.md @@ -398,3 +398,11 @@ 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__`. \ No newline at end of file