CONTRIBUTING: Make Reason upgrade instructions independent from Playground

Author: ryyppy

CONTRIBUTING.md

@@ -312,13 +312,14 @@ load the data. Right now we don't provide any instructions inside here yet, but
 [here's how the official ReasonML playground did
 it](https://github.com/reasonml/reasonml.github.io/blob/source/website/setupSomeArtifacts.js#L65).
 
-### Upgrading the Reason version
+## Upgrading the Reason version within BuckleScript
 
-The playground is shipping with a specific Reason syntax version, which currently needs to be updated manually once in a while.
-Paths to relevant files:
+Each BuckleScript release is coupled to a specific Reason syntax version, which currently needs to be updated manually once in a while.
 
-- `jscomp/main/refmt_api.ml`: Contains the programmatic interface for the refmt syntax converter (responsible for transforming Reason string code to an OCaml AST)
-- `lib/4.06.1/refmt_main3.ml`: The refmt binary used within BuckleScript itself. The `3` corresponds to the corresponding major version of refmt.
+It's important that we need to update two specific files:
+
+- `jscomp/main/refmt_api.ml`: Contains the programmatic interface for the refmt syntax converter (responsible for transforming Reason string code to an OCaml AST) -> Only used in the BuckleScript JS Playground
+- `lib/4.06.1/refmt_main3.ml`: The refmt binary used within BuckleScript itself. The `3` corresponds to the corresponding major version of refmt -> Used to build the vendored `refmt`, aka. `bsrefmt`
 
 Both files are generated by using the `jscomp/bin/bspack.exe` binary (which is also built automatically when you build the compiler inside this repository) on the refmt parser. In more detail, `bspack.exe` resolves all dependencies of one specific `.ml` input file, puts them in the right order and copies all the source code with the target input file in one huge `.ml` bundle.
 
@@ -332,7 +333,7 @@ git clone https://github.com/facebook/reason
 
 cd reason
 
-# You should already have created this switch by now, see playground build setup above
+# You should already have created this switch by now, see playground build setup instructions in "Contributing to the BS Playground Bundle"
 opam switch 4.06.1
 opam pin add -y reason .
 opam pin add -y rtop .
@@ -354,11 +355,19 @@ Now copy the files to bucklescript and do a rebuild to verify the changes:
 cp build/refmt_api.ml ../../bucklescript/jscomp/main/refmt_api.ml
 cp build/refmt_binary.ml ../../bucklescript/lib/4.06.1/refmt_main3.ml
 
+# Build the whole compiler
 node scripts/ninja.js config && node scripts/ninja.js build
+
+# Build the playground
 BS_PLAYGROUND=../playground node scripts/repl.js
 ```
 
-You should now have a new `playground/exports.js` with the new Reason version included.
+You should now have the newest `refmt` binary for the actual compiler, and for the playground, a new `playground/exports.js` file with the new Reason version included.
+
+**Important:** Always verify that the updated Reason version is in sync in the
+`refmt.exe` and the playground bundle. Use `lib/bsrefmt --version` and for the
+playground API `window.reason.version` (not final) to get the bundled
+version.
 
 ## Contributing to the Documentation