puter/packages/backend/doc/contributors/index.md

Contributing to Puter's Backend

Initial Reading

• puter-js-common's README.md
  • Whenever you see AdvancedBase, that's from here
    • Many things in backend extend this. Anything that doesn't only doesn't because it was written before AdvancedBase existed.
  • Allows adding "traits" to classes
    • Have you ever wanted to wrap every method of a class with common behavior? This can do that!

Where to Start

• Kernel, despite its intimidating name, is a relatively simple (< 200 LOC) class which loads the modules (modules register services), and then starts all the services.
• RuntimeEnvironment sets the configuration and runtime directories. It's invoked by Kernel.
• The default setup for running a self-hosted Puter loads these modules:
  • CoreModule
  • DatabaseModule
  • LocalDiskStorageModule
• HTTP endpoints are registered with WebServerService by these services:
  • ServeGUIService
  • PuterAPIService
  • FilesystemAPIService

Development Philosophies

The copy-paste rule

If you're copying and pasting code, you need to ask this question:

• am I copying as a reference (i.e. how this function is used),
• or am I copying an implementation of actual behavior?

If your answer is the first, you should find more than one piece of code that's doing the same thing you want to do and see if any of them are doing it differently. One of the ways of doing this thing is going to be more recent and/or (yes, potentially "or") more correct. More correct approaches are ones which reduce coupling, move from legacy implementations to more recent ones, and are actually more convenient for you to use. Whenever ever any of these three things are in contention it's very important to communicate this to the appropriate maintainers and contributors.

If your answer is the second, you should find a way to DRY that code.

Architecture Mistakes? You will make them and it will suck.

In my experience, the harder I think about the correct way to implement something, the bigger a mistake I'm going to make; unless a big part of the reason I'm thinking so hard is because I want to find a solution that reduces complexity and has the right maintenance trade-off. There's no easy solution for this so just keep it in mind; there are some things we might write 2 times, 3 times, even more times over before we really get it right and that's okay; sometimes part of doing useful work is doing the useless work that reveals what the useful work is.