From 38249a8967a59dc7f5b377de354d560dbfbf762a Mon Sep 17 00:00:00 2001
From: Ethan Roseman <ethteck@gmail.com>
Date: Wed, 17 Nov 2021 10:42:27 -0500
Subject: [PATCH] Propose new stuff for ifdefs (#534)

* propose new stuff for ifdefs

* oopth

* Update CONTRIBUTING.md
---
 CONTRIBUTING.md | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 413434e5e4..a3b8eaf72b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -95,11 +95,18 @@ Once you've matched a function, run the following:
 
 Then, go ahead and [create a pull request](https://github.com/pmret/papermario/pulls)!
 
-## NON_EQUIVALENT
+## Trouble matching a function
 
-If you make significant progress on a function but are unable to 100% match it, feel free to wrap it in a NON_EQUIVALENT check:
+Sometimes when working on a function, for various reasons, you'll be unable to match it. The following two sections describe what labels we give these functions and when. Any time you wrap a function in a label like this, please leave a comment above the function with a brief description of the issue(s).
+
+### NON_EQUIVALENT
+
+If you are working on a function but can't figure out how to tackle certain parts, or you're sure that it's not equivalent, you can wrap it in NON_EQUIVALENT.
+
+Please make a best-effort attempt on any function you put in a PR, though. Half-finished functions aren't necessarily much use to the next decomper.
 
 ```c
+// can't figure out the MULT_HI() stuff
 #ifdef NON_EQUIVALENT
 void func(void) {
     // ...
@@ -109,6 +116,19 @@ INCLUDE_ASM(void, "file", func, void);
 #endif
 ```
 
-## NON_MATCHING
+### NON_MATCHING
 
-If you are unable to match a function but are sure it behaves the same, wrap **equivalent** C code in NON_MATCHING.
+If you are unable to 100% match a function but are fairly certain it's equivalent in behavior, you can wrap the C code in NON_MATCHING.
+
+ ```c
+// s3/s4 swap
+#ifdef NON_MATCHING
+void func(void) {
+    // ...
+}
+#else
+INCLUDE_ASM(void, "file", func, void);
+#endif
+```
+
+Once the project is shiftable, NON_MATCHING functions will be used in place of the included ASM.