• A monorepo makes it much easier to do large refactors in dynamically typed languages via search/replace: after you craft your regex searches, its good to know you were searching the whole space of potentially affected files.
• A monorepo makes it much easier to implement uniform tooling across modules/libraries/systems/folders, which increases the confidence that “After mastering a few key technologies I can work in almost any part of the codebase”.
• See the “Collective Benefit Tomorrow” table above, most of those are enabled by the complementary combination of Monorepo+Monolith+CI.
  • For example it’s much easier to implement integration tests in a monorepo and over the long term things that are easy are things that tend to happen, which gives you “If my PR passes CI it won’t break code.org”

• The "marketing sites" of Code.org, CSForAll.org, etc, which have no dependency on the Code Studio Learning Platform and are owned by the Marketing department with occasional Engineering Support. Keeping this separate empowers consultants and focused engineers to work within that more modern and tidy repo without being distracted by the learning platform.
• 3rd Party Libraries we have forked (e.g. Blockly)
• Gems and NPMs we published that already have 3rd party traction
  • While we encourage releasing code as standalone open source packages hosted within the monorepo, please demonstrate significant 3rd party usage/interest/strategy before splitting the package out of the repo. Historically we’ve split first and then not gotten traction which resulted in lots of “eggs” (things outside the repo) but no “chickens” (3rd party uptake of our packages).

• See: The Majestic Monolith by DHH for why monolith and Microservices video by KRAZAM for why not microservices.
• Also see tenet below: “The Rails Way”.
• A monolith gives us a single uniform predictable deploy step: if I merge this PR here/now, I know when and how my code will be deployed, no matter what part of the codebase I changed.
• Avoids having to coordinate rollouts, esp in cases where old code may be using a very old or under documented deploy system.
• Microservices tend to improve dev productivity when you “horizontally scale” the number of devs and in the short-term to make small changes or new standalone services and when you have firm ownership boundaries, but decrease dev productivity when you want to “vertically scale” a small number of devs and in the long-term when you need to own a lot of code made by people in the past and when you want collective/fuzzy ownership boundaries.
  • In our situation we have a fixed+small horizontal scale AND we keep old code around for a long-time but still want to make occasional changes to it with confidence AND we prefer collective ownership.
• See the “Collective Benefit Tomorrow” table above, most of those are enabled by the complementary combination of Monorepo+Monolith+CI. E.g. “If my PR passes CI it won’t break code.org” requires coordination of both testing across repos but ALSO coordinated deployment which can be tricky with microservices.

• If it’s fundamentally harder for inviolable technical reasons you can consider a microservice. Wanting to use a new language is not a valid reason to deploy as a microservice unless use of that language is fundamentally required to achieve the feature (e.g. javabuilder inherently needs to use javac running on java, and is required because the feature goal was teaching java).
• This doesn’t restrict use of 3rd party services or open source servers e.g. its ok to deploy a redis instance or use a managed redis service (better). If we don’t “own the code”, it’s ok to stand up an instance.

• Gives long-term confidence that changing any part of our codebase (even ones forgotten years ago) will be flagged before PR merge by our CI system. Allows a team to confidently work on ALL parts of the codebase.
• Prevents accidental forks where multiple consumers of the same lib will change it not knowing the change breaks other consumers, and nobody will notice for months/years by which point nobody has time to unpin the de facto fork.
• Catches build errors before they’re merged so they can be fixed by the author rather than DOTD hunting down “whodoneit” a day/week/whatever later.
• See the “collective benefit tomorrow” tradeoff chart, most of those are enabled by the complimentary combination of Monorepo+Monolith+CI

• Chef Cookbooks: we don’t test these as part of our main CI build because it would be very technically challenging to do so as it requires modifying actual server instances.
• Non-exceptions: if your goal is bypassing “slow main CI tests” this tenet probably means you can’t unless you have no downstream consumers of your lib/service, or you can do full integration testing against all parts without running the whole test suite. Alternaive idea: consider optimizing our overall CI suite performance.

• We generally have simple "rails shaped", "mysql shaped" and "react shaped" problems that aren't very exotic and don't benefit significantly from exotic solutions.
• We have a significant investment in Ruby/Rails that makes it challenging to do a wholesale move to a different platform.
• We get productivity benefits from being a monolith, which means sticking with the same basic language + web framework.
• Ruby/Rails is working well. While other platforms (e.g., Go) may be more optimized/efficient, they don’t outweigh the effort that would be required to move.
• A single Ruby/Rails server-side architecture makes it easier for team members to move between different parts of the code base.
• We don't have sections of the code "go dark" when contributors leave the project taking with them the last knowledge of relatively obscure technology.
• A good general principle for code.org: given our problem space, we should usually be making pretty boring technology choices.

• When it is fundamentally impossible to implement a specified feature without using another language, e.g. Javabuilder uses Java because our curriculum goal required running Java code, which inherently requires Java.
• If it is not feasible to implement a feature in Ruby due to lack of libraries, Python may be invoked from ActiveJob (howto).
• May use short snippets of inline JS/JQuery without React on the client side, where pragmatic.
• May use bash or nodejs for general tooling when pragmatic (e.g. better nodejs apis than ruby)
• Consider Redis instead of MySQL when performance is important and ephemerality is acceptable (e.g. cache values)
• This tenet will probably have more exceptions and edge cases than most. Its not an exhaustive list, its a "highly preferred list".
  • Be pragmatic, do a good faith attempt to use preferred languages and frameworks, but solve your problems.
  • E.g. we also use cloudformation (etc etc) which could be argued to be kind of like a programming language, but is totally not a problem.
    • OTOH, you don't get to "use Haskell because everything else should be considered lame and fundamentally broken" 😉.

• Observing the codebase over a decade of dev: sometimes you can get a gain this year by customizing Rails to work a different way that’s a little better for us, but over time non-conventional code tends to become a maintenance burden.
• Often the “10% better” non-conventional code is exactly what prevents us from upgrading to the “50% better” official Rails solution to the problem that comes out 2 years later.
• By and large we have pretty conventionally Rails-shaped problems, which means Rails tends to solve our problems better than we would if we wait a little longer.
• Rails has been a great long-term fit to our problem space and we benefit from continuing to get upgrades as Rails has improved. Doing it “their way” makes upgrades happen semi-automatically.

* Sometimes deviating from stock Rails makes sense due to the large size of our application:
  * e.g. modularizing our rails app via [Rails engines](https://guides.rubyonrails.org/engines.html).
  * e.g. decoupling rails routes from being associated with individual models.

• Gives us the best of both worlds:
  • Self-hosting many open source servers, especially stateful services like DBs, requires ongoing infra admin work and monitoring attention. We have a small team.
  • Developing against an API with an Open Source implementation gives us flexibility:
    • …to implement a “local dev” for the service using the open source version
    • …to change vendors if need be (cost, availability, in-kind donations, etc)

• KISS: REST has been a simple and an effective match to our needs.
• Our labs and other fat client-side JS apps don’t tend to have the “complex aggregation of dynamic data from many sources” property that benefits from more complex systems like GraphQL.
• REST APIs inherently support HTTP caching mechanisms (e.g., ETag, Last-Modified, Cache-Control), enabling better performance and reducing load on the server.

• Provides a common deployment and development pattern across our engineering teams.
• Decreases the work required to port our services between cloud providers
• Easier to build a local dev environment that effectively mimics prod

• Any storage layer in production (e.g., MySQL/RDS/S3) should not be containerized.
• We will still rely on vendor-specific templates for infrastructure configuration (e.g., Cloud Formation)
• Scripts can still be helpful to make complex multi-step operations easier/clearer