During the ongoing community Doc-A-Thon, different discussions have arisen. I want to mention a couple of them related to the common settings between LMS and CMS.
I’m working on documenting a set of settings that are defined for both, LMS and CMS, independently, which means that those settings can be configured using different values for every service variant. The setting RETIRED_EMAIL_DOMAIN is an example of a setting defined in both, LMS and CMS independently. The main question here is if it’s required to annotate the setting in both env files.
When researching the settings to add the annotations, I realized that it’s not necessary to define these settings in both, LMS and CMS env files. From my point of view, we could use the import in here to copy the defaults from LMS to CMS. Is this discussion out of the Doc-A-Thon scope, or is this a good opportunity to apply those changes?
Thanks @jhony_avella. Great questions. Both are worth discussing and they are highly related.
My short answer is to propose the following:
Document both the LMS and CMS settings using annotations. Have the CMS annotations refer to the LMS annotations rather than duplicating text. If the descriptions need to differ, than just make them different. Use the warning annotation to highlight if the annotation needs to be set in both LMS and CMS with the same value, or any other non-obvious considerations.
For toggle (boolean) settings, we can consider replacing with a SettingToggle or SettingDictToggle, and potentially removing the default override. See the linked ADR for more details on this.
Longer answer:
I think OEP-45: Configuring and Operating Open edX relates to your second question. I think the OEP has us moving towards clear and independent settings. We are moving in this direction, but we still don’t have files defined as proposed, like defaults.py. I don’t think the OEP addresses how to ensure settings that need to be consistent across services are kept consistent. For now, a good initial step would be to at least document that fact. Adding tooling to lint/enforce these types of rules could come later, but I haven’t heard anything about that.
Based on this, I’m guessing we would be moving away from the cross-service import you indicated, but I need to check my understanding of this. Either way, I’d like to get this clearly documented. If we should no longer be following that practice, we should comment that it is deprecated. Again, I am not confident yet in my answer, so I will have this checked.
Let me know what you think of my proposal. Thanks.
@robrap I think what you said is correct. We’re slowly moving towards more and more logical separation between the LMS and Studio and I think relying on that import is not viable in the long term.
@jhony_avella: An alternative to my original proposal that I am leaning toward is simply adding a comment in CMS like:
# See annotations in lms/envs/common.py for details.
This assumes that the annotation warns the user that the value should match in both. This avoids duplicating the rest of the annotations as well, like creation date, etc.
@robrap I agree with your latest approach. I’m documenting non-toggle settings so it would be pretty simple to keep the standard annotations and just reference the LMS annotation on the “setting_description” CMS annotation, but for toggles, it’s a lot of duplication. I’ll proceed with this one line comment approach in my PR’s. This short version should be only used when it really applies; as you mentioned in your first approach, maybe the same setting requires a different specification according to the service variant where it’s defined.
@jhony_avella: Would you be willing to updated the FAQ with instructions for this? You could include a reference to your PR as well if it helps. Thank you!