docs: OEP-67 - Document our best practice tools and tech. #518

feanil · 2023-09-05T20:05:59Z

The topic for consideration in this PR

We should have an OEP to help us know which tools and technology we as a community should standardize on. This OEP will help us track these items and provide a structure place for us to have future conversations when we want to change community standards.

We currently have some of this for the frontend but having something a
bit more standard across the entire ecosystem would be helpful for
making decisions going forward.

Note for Reviewers: The tools/standards in the frontend section were simply moved from OEP-11, they are NOT up for re-consideration in this PR. If they are wrong or need updates, I recommend supporting this OEP and then making a new ADRs to update a recommendation that you feel is incorrect.

Tasks for After the OEP is Approved

Update OEP-11 to be superseded
Move ADRs from OEP-11 to OEP-67
Generate all the relevant redirects.
Add a new overall ADR for Codecov, since technically it moves from being a frontend recommendation to being an overall recommendation.

brian-smith-tcril · 2023-09-05T20:13:12Z

This is great! It looks like everything (except for Codecov) from OEP-11 can go under the "Frontend Technology Selection" section as it's all pretty frontend specific.

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

e0d

Review of the current draft.

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

kdmccormick

Thanks Feanil. This is long overdue. A few comments but I'm very supportive of the overall direction.

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

kdmccormick · 2023-09-13T20:13:16Z

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

+* OEP-11 will be superseded.
+
+* All ADRs under OEP-11 will be moved to be under this OEP instead.


Yay for consolidation!

kdmccormick · 2023-09-13T20:15:30Z

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

+#. **Use Redux**
+
+   For state management of complex
+   client-side interactions, Redux must be used. This library was chosen
+   because it sees strong use in the React community, but is also flexible
+   enough to be used in situations where a hybrid React/Backbone architecture
+   exists.


I remember David Joy saying at one point that Redux wasn't worth the hassle and that MFE devs should feel free to simply not use it.

I'm not sure if I remember that right or whether that statement still applies, I'd need @arbrandes or @brian-smith-tcril 's input.

(I guess this is the sort of thing that will make this OEP useful :)

This is a copy from the current frontend OEP. I think any corrections should be made as follow-up ADRs and updates to the OEP.

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

jmbowman · 2023-09-19T13:29:12Z

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

+   Python code - see `OEP 18`_ for more information. For more information on
+   package-lock files see `Package Lock`_.
+
+#. **Keep dependencies up to date by using Greenkeeper**


Shouldn't this recommend Renovate instead? See https://openedx.atlassian.net/wiki/spaces/AC/pages/1841791377/Set+up+Renovate+to+Automate+JavaScript+Dependency+Updates#Notes-on-Alternatives for reasons we started to ditch Greenkeeper. As with the Redux note above we could update it after initial release, but I'd rather not risk people trying to start switching to Greenkeeper after reading this.

Yea, I think this should be a follow-up task, I made #524 to track the work.

deborahgu

all but one of my comments are grammar nits, for which I apologize; , because I know it is early days yet. It's just, it seemed a waste not to make the notes as I read.

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

deborahgu · 2023-09-19T16:26:05Z

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

+
+#. **Use React**
+
+   **Rationale**: React must be used for building new UIs, as it is


re: must. I am new enough around here that I don't know the standard, but I always assume that if a spec is using RFC 2119 verbs meaningfully, they should be capitalized, e.g. MUST, MAY, just to clarify what requirements really are.

that's a fair point, I'm not sure what the intent of the original authors was here, per your second point, MUST feels like a lot here to me as well but I'm not sure what the current stance should be. This is probably worth a follow-up conversation in the frontend working group. @brian-smith-tcril @arbrandes @adamstankiewicz what do you think?

Yeah, I actually think we're squarely in SHOULD-land; even React. This definitely deserves a dedicated conversation.

deborahgu · 2023-09-19T16:27:16Z

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

+
+#. **Use React**
+
+   **Rationale**: React must be used for building new UIs, as it is


Is the guidance really MUST on React? Some UIs are going to be so simple that react is overkill. (See above regarding: "new around here"; if this debate has already been had and resolved then I don't need anybody to restart it for me. It's more a question about unexamined assumptions.)

@deborahgu If a UI isn't using React, at least one possible concern is the compatibility with using the Paragon design system and React-based UI component library in terms of brand consistency, etc. across UI projects within Open edX.

yeah, this is a bigger question than can be resolved in this OEP, but eg. right now we're working on a place where we're dealing with the entire Paragon dependency stack to render 100% static pages, and it's not lightweight. It might be fundamentally worth the cost, but the cost is not small.

feanil · 2023-10-12T20:17:19Z

@bradenmacdonald the review period is complete, I think there are a lot of follow-up updates but as far as I can tell, no disagreement on this OEP existing and the goals it's trying to solve for. Do you have any concerns that I should address because I make the rest of the re-organization changes and land this OEP?

bradenmacdonald · 2023-10-12T20:49:39Z

@feanil Nope! I don't have any concerns, and I think people seem quite happy with this change. (And eager to make the follow-up updates, as it seems like quite a few things have gotten outdated from the original.)

kdmccormick

LGTM, pending a couple formatting fixes.

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

kdmccormick · 2023-10-12T20:29:58Z

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

+Consequences
+************
+
+* OEP-11 will be superseded.


Friendly reminder to go into OEP-11 and make this change.

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

bradenmacdonald · 2023-10-12T20:58:37Z

@feanil Also, can we track all the follow-up ADRs known to be needed in one place? I see codecov is in the PR description, greenkeeper is #524, Redux is not tracked, etc.

feanil · 2023-10-13T14:22:12Z

@bradenmacdonald good call, I'll make a new top-level issue and collect all the known updates we need into that for now.

feanil · 2023-10-16T16:45:04Z

@bradenmacdonald I've created #531 to track the current known updates that we need. Let me know if you think there's anything else that needs to be done before we land this.

bradenmacdonald

@feanil Thanks for making #531 . I think this is ready to go!

oeps/best-practices/oep-0067-bp-tools-and-technology.rst

We currently have some of this for the frontend but having something a bit more standard acrooss the entire ecosystem would be helpful for making decisions going forward. We also: * Replace OEP-11 and relocate its ADRS to OEP-67 * Add redirects from old doc locations to the new locations for any docs that moved. Co-authored-by: Kyle McCormick <kdmc@pm.me> Co-authored-by: Ned Batchelder <ned@edx.org> Co-authored-by: Deborah Kaplan <deborahgu@users.noreply.github.com> Co-authored-by: Braden MacDonald <braden@opencraft.com>

brian-smith-tcril reviewed Sep 5, 2023

View reviewed changes

oeps/best-practices/oep-0067-bp-tools-and-technology.rst Show resolved Hide resolved

e0d reviewed Sep 7, 2023

View reviewed changes

oeps/best-practices/oep-0067-bp-tools-and-technology.rst Outdated Show resolved Hide resolved

oeps/best-practices/oep-0067-bp-tools-and-technology.rst Outdated Show resolved Hide resolved

oeps/best-practices/oep-0067-bp-tools-and-technology.rst Show resolved Hide resolved

kdmccormick reviewed Sep 13, 2023

View reviewed changes

feanil mentioned this pull request Sep 14, 2023

Advise on library for Django model field encryption-at-rest openedx/wg-security#37

Open

feanil changed the title ~~docs: Document our best practice tools and tech.~~ docs: OEP-67 - Document our best practice tools and tech. Sep 18, 2023

feanil marked this pull request as ready for review September 18, 2023 17:24

pshiu reviewed Sep 19, 2023

View reviewed changes

oeps/best-practices/oep-0067-bp-tools-and-technology.rst Show resolved Hide resolved

jmbowman reviewed Sep 19, 2023

View reviewed changes

deborahgu reviewed Sep 19, 2023

View reviewed changes

arbrandes mentioned this pull request Oct 5, 2023

OEP-11 Frontend Technology Updates (Epic) #480

Open

4 tasks

kdmccormick approved these changes Oct 12, 2023

View reviewed changes

feanil force-pushed the feanil/oep-67-tools-and-tech branch 2 times, most recently from acd775a to 5c86934 Compare October 16, 2023 15:49

feanil mentioned this pull request Oct 16, 2023

Update Technology Recommendations and Related Decisions #531

Open

7 tasks

bradenmacdonald approved these changes Oct 16, 2023

View reviewed changes

oeps/best-practices/oep-0067-bp-tools-and-technology.rst Outdated Show resolved Hide resolved

oeps/best-practices/oep-0067-bp-tools-and-technology.rst Outdated Show resolved Hide resolved

feanil force-pushed the feanil/oep-67-tools-and-tech branch from 3689a0d to 80aeb92 Compare October 16, 2023 19:26

feanil merged commit b9faa6c into master Oct 16, 2023
2 checks passed

feanil deleted the feanil/oep-67-tools-and-tech branch October 16, 2023 19:43

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: OEP-67 - Document our best practice tools and tech. #518

docs: OEP-67 - Document our best practice tools and tech. #518

feanil commented Sep 5, 2023 •

edited

Loading

brian-smith-tcril commented Sep 5, 2023 •

edited

Loading

e0d left a comment

kdmccormick left a comment

kdmccormick Sep 13, 2023

kdmccormick Sep 13, 2023

feanil Sep 18, 2023

jmbowman Sep 19, 2023

feanil Sep 25, 2023

deborahgu left a comment

deborahgu Sep 19, 2023

feanil Sep 25, 2023

arbrandes Sep 27, 2023 •

edited

Loading

deborahgu Sep 19, 2023

adamstankiewicz Sep 25, 2023

deborahgu Sep 26, 2023

feanil commented Oct 12, 2023

bradenmacdonald commented Oct 12, 2023

kdmccormick left a comment

kdmccormick Oct 12, 2023

bradenmacdonald commented Oct 12, 2023

feanil commented Oct 13, 2023

feanil commented Oct 16, 2023

bradenmacdonald left a comment

		* OEP-11 will be superseded.

		* All ADRs under OEP-11 will be moved to be under this OEP instead.


		#. Use React

		Rationale: React must be used for building new UIs, as it is

docs: OEP-67 - Document our best practice tools and tech. #518

docs: OEP-67 - Document our best practice tools and tech. #518

Conversation

feanil commented Sep 5, 2023 • edited Loading

The topic for consideration in this PR

Tasks for After the OEP is Approved

brian-smith-tcril commented Sep 5, 2023 • edited Loading

e0d left a comment

Choose a reason for hiding this comment

kdmccormick left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

deborahgu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

arbrandes Sep 27, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

feanil commented Oct 12, 2023

bradenmacdonald commented Oct 12, 2023

kdmccormick left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bradenmacdonald commented Oct 12, 2023

feanil commented Oct 13, 2023

feanil commented Oct 16, 2023

bradenmacdonald left a comment

Choose a reason for hiding this comment

feanil commented Sep 5, 2023 •

edited

Loading

brian-smith-tcril commented Sep 5, 2023 •

edited

Loading

arbrandes Sep 27, 2023 •

edited

Loading