From e5bb4e6961cb424103e00501c85ddf6242a0f183 Mon Sep 17 00:00:00 2001
From: Bloop <13398309+vinylspiders@users.noreply.github.com>
Date: Sat, 9 Dec 2023 10:25:10 -0500
Subject: [PATCH] Updates the modularization guide with TGUI instructions
 (#25514)

* Adds TGUI to the modularization guide

* Update readme.md

* Update readme.md

* Update readme.md

* Update readme.md

* Update readme.md

* Update readme.md

* Update readme.md

* More examples

* Update readme.md

* Update readme.md

* Update readme.md
---
 modular_skyrat/readme.md | 69 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 67 insertions(+), 2 deletions(-)

diff --git a/modular_skyrat/readme.md b/modular_skyrat/readme.md
index da3e41596eba3b..b54f8539581fdd 100644
--- a/modular_skyrat/readme.md
+++ b/modular_skyrat/readme.md
@@ -127,7 +127,7 @@ It also helps prevent modules needlessly overriding the same proc multiple times
 
 This section will be fairly straightforward, however, I will try to go over the basics and give simple examples, as the guide is aimed at new contributors likewise.
 
-The rule of thumb is that if you don't absolutely have to, you shouldn't make any changes to core codebase files.
+The rule of thumb is that if you don't absolutely have to, you shouldn't make any changes to core codebase files. With some exceptions that will be mentioned shortly.
 
 In short, most of the modular code will be placed in the subfolders of your main module folder **`modular_skyrat/modules/yourmodule/code/`**, with similar rules as with the assets. Do not mirror core code folder structures inside your modular folder.
 
@@ -145,7 +145,19 @@ Such modules, unless _very_ simple, **need** to have a `readme.md` in their fold
 
 ## Modular Overrides (Important!!)
 
-Note, that it is possible to append code in front, or behind a core proc, in a modular fashion, without editing the original proc, through referring the parent proc, using `..()`, in one of the following forms.  And likewise, it is possible to add a new var to an existing datum or obj, without editing the core files.
+Note, that it is possible to append code in front, or behind a core proc, in a modular fashion, without editing the original proc, through referring the parent proc, using `. = ..()` or `..()`. And likewise, it is possible to add a new var to an existing datum or obj, without editing the core files.
+
+**Note about proc overrides: Just because you can, doesn't mean you should!!**
+
+In general they are a good idea and encouraged whenever it is possible to do so. However this is not a hard rule, and sometimes Skyrat edits are preferable. Just try to use your common sense about it.
+
+For example: please do not copy paste an entire TG proc into a modular override, make one small change, and then bill it as 'fully modular'. These procs are an absolute nightmare to maintain because once something changes upstream you have to update the overridden proc.
+
+Sometimes you aren't even aware the override exists if it compiles fine and doesn't cause any bugs. This often causes features that were added upstream to be missing here. So yeah. Avoid that. It's okay if something isn't fully modular. Sometimes it's the better choice.
+
+The best candidates for modular proc overrides are ones where you can just tack something on after calling the parent, or weave a parent call cleverly in the middle somewhere to achieve your desired effect.
+
+Performance should also be considered when you are overriding a hot proc (like Life() for example), as each additional call adds overhead. Skyrat edits are much more performant in those cases. For most procs this won't be something you have to think about, though.
 
 ### These modular overrides should be kept in `master_files`, and you should avoid putting them inside modules as much as possible.
 
@@ -297,6 +309,59 @@ This also applies to files, do not comment out entire files, just delete them in
 
 **This does not apply to non-modular changes.**
 
+## Modular TGUI
+
+TGUI is another exceptional case, since it uses javascript and isn't able to be modular in the same way that DM code is.
+ALL of the tgui files are located in `/tgui/packages/tgui/interfaces` and its subdirectories; there is no specific folder for Skyrat UIs.
+
+### Modifying upstream files
+
+When modifying upstream TGUI files the same rules apply as modifying upstream DM code, however the grammar for comments may be slightly different.
+
+You can do both `// SKYRAT EDIT` and `/* SKYRAT EDIT */`, though in some cases you may have to use one over the other.
+
+In general try to keep your edit comments on the same line as the change. Preferably inside the JSX tag. e.g:
+
+```js
+<Button
+	onClick={() => act('spin', { high_quality: true })}
+	icon="rat" // SKYRAT EDIT ADDITION
+</Button>
+```
+
+```js
+<Button
+	onClick={() => act('spin', { high_quality: true })}
+	// SKYRAT EDIT ADDITION START - another example, multiline changes
+	icon="rat"
+	tooltip="spin the rat."
+	// SKYRAT EDIT ADDITION END
+</Button>
+```
+
+```js
+<SomeThing someProp="whatever" /* it also works in self-closing tags */ />
+```
+
+If that is not possible, you can wrap your edit in curly brackets e.g. 
+
+```js
+{/* SKYRAT EDIT ADDITION START */} 
+<SomeThing>
+	someProp="whatever"
+</SomeThing>
+{/* SKYRAT EDIT ADDITION END */}
+```
+
+### Creating new TGUI files 
+
+**IMPORTANT! When creating a new TGUI file from scratch, please add the following at the very top of the file (line 1):**
+```js
+// THIS IS A SKYRAT UI FILE
+```
+
+This way they are easily identifiable as modular TGUI .tsx/.jsx files. You do not have to do anything further, and there will never be any need for a Skyrat edit comment in a modular TGUI file.
+
 ## Exemplary PR's
 
 Here are a couple PR's that are great examples of the guide being followed, reference them if you are stuck: