docs: Settings Simplification ADR

[kdmccormick]

https://github.com/kdmccormick/edx-platform/blob/kdmccormick/settings-adr/docs/decisions/0022-settings-simplification.rst

[kdmccormick]

@feanil , could you take a first pass? Once it looks good to you, I'll circulate it more broadly.

[feanil]

A few minor comments but nothing major. I can re-review once those are addressed.

[kdmccormick]

@regisb , your wisdom on this ADR would be invaluable.

[kdmccormick]

Sorry @feanil , forgot to push. Ready now.

[feanil]

Looks good to me now.

[regisb]

Reading this ADR, I found myself nodding and mumbling "yes, yes, ok..." all the way down. I used to tell people that there are just two things which are difficult in Open edX: static assets and settings. I'm grateful that you are tackling the latter after having greatly improved the state of the former.

My comments are mostly questions for my own understanding. As far as I'm concerned this is good to go.

[robrap]

Thank you.

[kdmccormick]

@feanil @regisb I've made some edits to the structure of the ADR and clarified some details based on Robert's feedback. If you want to re-review before I merge, please do so soon.

[robrap]

Thanks @kylecrawshaw. A couple of thoughts:

1. First, I realized that the term third-party was confusing to me. In the context of the Open edX platform, I'm used to the term third-party being applied to libraries (e.g. Django, DRF) and tools. Even the term third-party provider, I would typically associate with examples like: AWS, Azure, Confluent, etc., and not with Open edX providers, unless specifically designated.

• a. Below you used the phrase "third-party providers (like edx.org)", and that was clear to me, but only because the example was edx.org, and it took me a moment to re-orient myself. I'm wondering if switching this to "Open edX providers (like edx.org)", or something like that, would be more clear?
• b. The reference <third_party_repo> is again ambiguous (on its own, and it is opening this paragraph), and maybe this could be <open_edx_provider_repo>? I also realized that you wanted a term that would cover tools like Tutor. Maybe <open_edx_provider_or_tool_repo>?
• c. Related, there are a bunch of references to third-party settings in this ADR, and now I'm not clear which are third-party library settings, and which are Open edX provider settings? Maybe you could search for third-party through the ADR and double-check whether being slightly more explicit will bring clarity?

2. This step is written as if it is required, but the consequences section better details the possible alternative of using lms/envs/yaml.py. Maybe that was part of my original confusion? Is there some way to make this clear, if I am understanding correctly?

[kdmccormick]

First, I realized that the term third-party was confusing to me. In the context of the Open edX platform, I'm used to the term third-party being applied to libraries (e.g. Django, DRF) and tools. Even the term third-party provider, I would typically associate with examples like: AWS, Azure, Confluent, etc., and not with Open edX providers, unless specifically designated.

You're right, I didn't even realize I was using 3rd-party to mean two different things. I'll update to disambiguate. <open_edx_provider_or_tool_repo> is a good idea.

This step is written as if it is required, but the consequences section better details the possible alternative of using lms/envs/yaml.py. Maybe that was part of my original confusion? Is there some way to make this clear, if I am understanding correctly?

Ah, fair. The uncertainty of whether we implement yaml.py has certainly made this ADR harder to write 😛 I will attempt to clarify that that what we're trying to communicate to providers & tools is: !(we_decide_to_support_yaml && you_decide_to_use_yaml) => you_need_a_custom_settings_file

[kdmccormick]

@feanil @robrap @regisb updated with Robert's suggested clarifications. Feel free to re-review today, or let me know today if you'd like to re-review but need more time.

[robrap]

Thanks for all the updates!

[edx-pipeline-bot]

2U Release Notice: This PR has been deployed to the edX staging environment in preparation for a release to production.

[edx-pipeline-bot]

2U Release Notice: This PR has been deployed to the edX production environment.

[edx-pipeline-bot]

2U Release Notice: This PR has been deployed to the edX production environment.