More contribution docs

Author: chenglou

CONTRIBUTING.md

@@ -8,18 +8,33 @@ They should be synced in from the `bsb` build. Don't take them from other places
 
 ### `.compiler.log`
 
-The build output is streamed into `lib/bs/.compiler.log`. Here are its various states:
+The build output is streamed into `lib/bs/.compiler.log`. Here are its various states, numbered here:
 
-- Doesn't exist: artifacts not built yet, or cleaned away.
-- Present but empty: currently building, no error yet.
-- Present, non-empty, without a final line `# Done`: still building.
-- Present, with the final line `# Done`: finished building.
+1. Doesn't exist: artifacts not built yet, or cleaned away.
+2. Present but empty: currently building, no error yet.
+3. Present, non-empty, without a final line `# Done`: still building.
+4. Present, with the final line `# Done`: finished building.
 
 Barring FS errors, there should be no other state to `.compiler.log`.
 
-### States of Diagnostics
+### State 1
 
-- Artifacts cleaning through `bsb -clean` removes `.compiler.log`, as mentioned above. If that's the case, remove the diagnostics in the editor too. One could argue that they should be kept, but that's misleading UX-wise, and harder to implement correctly.
+Artifacts cleaning through `bsb -clean` removes `.compiler.log` and turns into state 1. If that's the case, remove the diagnostics in the editor too. One could argue that they should be kept, but that's misleading UX-wise, and harder to implement correctly.
+
+### Streaming Update of Diagnostics
+
+After saving a file and running the build, the results stream into the log file. Unfortunately, UX-wise, in the editor, this might look like the diagnostics are suddenly gone then coming back in file by file. This looks bad. To remediate:
+- If the log file is in state 2 (see state numbers above), don't wipe the existing diagnostics yet.
+- If it's in state 3, update those particular files' diagnostics.
+- If in state 4, finish by clean up the rest of the old diagnostics. This means there's a bit of bookeeping needed here. Make sure you get it right. It's possible for a build to be interrupted (and therefore state 4 never reached) and restarted.
+
+Even this fix isn't great. Ideally, the editor's diagnostics can be greyed out while we're updating them...
+
+### Stale Diagnostics Detection
+
+To check whether the artifacts are stale, do **not** check `.bsb.lock` at the project root. This is unreliable, since it's possible that `bsb` wasn't running in watcher mode. We also don't want to encourage overuse of the watcher mode, though it seems increasingly common.
+
+<!-- Instead, do `bsb.exe -- -n` -->
 
 ### Files from Other Projects
 
@@ -45,6 +60,8 @@ The formatted result should be taken as-is, without any extra string trimming an
 
 ### Formatting Errors
 
+The errors returned from `bsc.exe -format` should be discarded; in theory, they should have been duplicates of the errors from `.compiler.log`.
+
 - should the format still show errors when the build isn't running?
 - should it show during various states of `.compiler.log`?